@bcmyguest/openmem 0.0.0-stage → 0.6.3

package/providers/cognee/manifest.json

@@ -0,0 +1,56 @@
+{
+  "id": "cognee",
+  "label": "Cognee",
+  "status": "supported",
+  "notes": "Self-hosted graph/RAG memory run as a pinned cognee/cognee image (single container, SQLite + LanceDB + Ladybug) on a loopback port in single-user mode (no authentication). Ingestion is asynchronous: the indexer adds documents, then requests cognify once per changed dataset, so a document is searchable only after the graph is built. Default cognify path is local GLiNER + FastEmbed (no API key); alternatives are LLM_PROVIDER=ollama or an OpenAI-compatible LLM_API_KEY. No coding-agent plugin — agents use the REST API on the loopback port (/docs).",
+  "settings": {
+    "nativeDocs": "https://docs.cognee.ai/",
+    "nativeConfigPaths": [
+      "~/.config/personal-memory/cognee.env",
+      "~/.config/personal-memory/cognee-indexer.env"
+    ],
+    "wizardOwns": [
+      "compose profile 'cognee', the loopback host port (COGNEE_PORT, default 8766) and the stack .env entries",
+      "GRAPH_EXTRACTOR / EMBEDDING_* (default GLiNER + FastEmbed) and optional LLM_* settings in cognee.env (mode 600, outside the repo)",
+      "the smoke test (health, dataset, multipart add, list, delete; recall is skipped because ingestion is asynchronous)",
+      "index.yml sources (shared indexer)",
+      "Cognee dataset mapping from indexer banks (the indexer sink maps each bank to a dataset)"
+    ]
+  },
+  "compose": {
+    "services": ["cognee", "indexer"],
+    "healthService": "cognee",
+    "logServices": ["cognee"],
+    "healthPath": "/health",
+    "hostPortEnv": "COGNEE_PORT",
+    "defaultHostPort": 8766,
+    "profile": "cognee",
+    "files": ["providers/cognee/compose.yaml"]
+  },
+  "indexer": {
+    "apiUrlEnv": "COGNEE_API_URL",
+    "sink": "cognee",
+    "sinkDriver": "cognee-rest"
+  },
+  "codingAgent": {
+    "pluginPackage": null,
+    "configTemplate": null,
+    "notes": "No plugin package. setupCodingAgent prints REST paths and registers the read-only Cognee MCP (cognee_health / cognee_search) in ~/.cursor/mcp.json."
+  },
+  "wizardHooks": {
+    "module": "wizard.mjs",
+    "delegates": {}
+  },
+  "wizard": {
+    "smokeBank": "wizard-smoke",
+    "retainMethod": "POST",
+    "retainPath": "/api/v1/add",
+    "retainBody": "multipart/form-data: datasetName=wizard_smoke, data=wizard-smoke.md (done by the smoke hook)",
+    "recallMethod": "POST",
+    "recallPath": "/api/v1/search",
+    "recallBody": "{\"searchType\":\"GRAPH_COMPLETION\",\"query\":\"What is the project codename?\",\"datasets\":[\"wizard_smoke\"]}",
+    "recallHint": "check {compose} logs cognee and cognify settings (GLiNER/FastEmbed, Ollama, or LLM_API_KEY)",
+    "deleteMethod": "DELETE",
+    "deletePath": "/api/v1/datasets/{bank}"
+  }
+}

package/providers/cognee/wizard.mjs

@@ -0,0 +1,134 @@
+/**
+ * Cognee sub-wizard (hook API v2). Cognee runs as a pinned docker service on a loopback
+ * port in single-user mode; its secrets (LLM_API_KEY) live in an operator env file outside
+ * the repo (default ~/.config/personal-memory/cognee.env), never in the stack .env,
+ * wizard.conf, config.toml, the summary or an error message. See lib/ for the
+ * implementations and docs/provider-wizard-hooks.md for the hook contract.
+ *
+ * This module must not import wizard/lib/run-wizard.mjs; it receives `helpers`.
+ */
+import { applyConfig, configToml as buildConfigToml } from "./lib/config.mjs";
+import { clackSetup as askInClack } from "./lib/clack.mjs";
+import { setupCodingAgent as printRestAgentHelp } from "./lib/coding-agent.mjs";
+import { beforeStack as prepareEnvDirs, stackEnv as cogneeStackEnv } from "./lib/env-setup.mjs";
+import { captureSecrets, configureLlm } from "./lib/llm-env.mjs";
+import { resolvePorts as resolveCogneePorts } from "./lib/ports.mjs";
+import { runSmoke } from "./lib/smoke.mjs";
+import { ensureState } from "./lib/state.mjs";
+import { summary as cogneeSummary } from "./lib/summary.mjs";
+import { validateCognee } from "./lib/validate.mjs";
+
+// Called by scripts/setup.mjs (the stack .env writer), not by the wizard.
+export { prepareStackEnv, setupNotices } from "./lib/stack-env.mjs";
+
+/** @typedef {import('../../wizard/lib/provider-wizard/helpers.mjs').ProviderWizardHelpers} Helpers */
+
+/**
+ * Quiet: fill Cognee's context fields, map the `[memory.cognee]` TOML table (port,
+ * env_file, indexer_env_file) into the environment when the environment did not set it, and
+ * take the secret answers (PM_COGNEE_LLM_API_KEY and friends) out of `process.env`. This
+ * runs before the wizard's first docker call, so no child process inherits a key.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function init(ctx, h) {
+  applyConfig(ctx, h);
+  captureSecrets(ctx);
+}
+
+/**
+ * Quiet: nothing to restore. The saved port is picked up in `resolvePorts`, which runs
+ * before this hook; nothing secret is saved anywhere.
+ * @param {Record<string, any>} ctx
+ */
+export async function hydrate(ctx) {
+  ensureState(ctx);
+}
+
+/** The single host port (COGNEE_PORT, default 8766). */
+export const resolvePorts = resolveCogneePorts;
+
+/**
+ * Step "LLM / embeddings": write cognify settings (default GLiNER + FastEmbed, or Ollama /
+ * OpenAI answers given as PM_COGNEE_<NAME>) into the operator env file. Never fails for a
+ * missing cloud key: the default local path is cognify-ready without one.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function configureModelRouting(ctx, h) {
+  await configureLlm(ctx, h);
+}
+
+/**
+ * Quiet: description and environment for the stack setup script (scripts/setup.mjs).
+ * @param {Record<string, any>} ctx
+ */
+export function stackEnv(ctx) {
+  return cogneeStackEnv(ctx);
+}
+
+/**
+ * Create the env directories (mode 700) before the stack setup masks them; warn about
+ * loose modes.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function beforeStack(ctx, h) {
+  await prepareEnvDirs(ctx, h);
+}
+
+/**
+ * Replaces the manifest smoke test: health, create dataset, multipart add, list, delete.
+ * Recall is not checked (ingestion is asynchronous).
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function smoke(ctx, h) {
+  await runSmoke(ctx, h);
+}
+
+/**
+ * Appends to ctx.validationErrors / ctx.validationChecks after the shared checks.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function extendValidation(ctx, h) {
+  validateCognee(ctx, h);
+}
+
+/**
+ * Quiet: tables merged into config.toml (`[memory.cognee]`: port, env_file; no secrets).
+ * @param {Record<string, any>} ctx
+ */
+export function configToml(ctx) {
+  return buildConfigToml(ctx);
+}
+
+/**
+ * Quiet: lines for the closing summary.
+ * @param {Record<string, any>} ctx
+ */
+export function summary(ctx) {
+  return cogneeSummary(ctx);
+}
+
+/**
+ * Clack-only: choose OpenAI key vs Ollama; for OpenAI, ask with a hidden prompt. Answers
+ * reach the wizard as PM_COGNEE_* in its own process environment.
+ * @param {Record<string, any>} ctx
+ * @param {typeof import("@clack/prompts")} ui
+ * @param {Helpers} h
+ */
+export async function clackSetup(ctx, ui, h) {
+  return askInClack(ctx, ui, h);
+}
+
+/**
+ * After the generic coding-agent step (skipped: no pluginPackage): print how agents talk
+ * to Cognee over REST on the loopback port.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function setupCodingAgent(ctx, h) {
+  await printRestAgentHelp(ctx, h);
+}

package/providers/graphiti/manifest.json

@@ -0,0 +1,15 @@
+{
+  "id": "graphiti",
+  "label": "Graphiti",
+  "status": "planned",
+  "notes": "Placeholder for Zep Graphiti temporal knowledge graph backend.",
+  "settings": {
+    "nativeDocs": "https://help.getzep.com/graphiti",
+    "nativeConfigPaths": [],
+    "wizardOwns": []
+  },
+  "compose": { "profile": "graphiti", "files": [], "services": [] },
+  "indexer": { "apiUrlEnv": "GRAPHITI_API_URL", "sink": "graphiti" },
+  "codingAgent": { "pluginPackage": null, "configTemplate": null },
+  "wizard": {}
+}

package/providers/hindsight/lib/clack.mjs

@@ -0,0 +1,245 @@
+/**
+ * Hindsight's questions for the Clack setup UI: model backend, models, reflect model.
+ * The meta UI asks the provider-neutral questions (action, provider) and then calls
+ * clackSetup; the returned environment is handed to the wizard so it skips its own
+ * model prompts (WIZARD_SKIP_BACKEND_STEP).
+ */
+import { applyConfigEnv } from "./config.mjs";
+import { fetchJson, normalizeOpenAiBase, ollamaModelNames, openAiModelIds } from "./probe.mjs";
+import {
+  LEMOND_DEFAULT_MODEL,
+  OLLAMA_COMPOSE_API_BASE,
+  OLLAMA_DEFAULT_MODEL,
+  OLLAMA_HOST_API_BASE,
+} from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+/**
+ * @param {{ repoRoot: string, home: string, wizardConf: string, pmMerged?: Record<string, unknown> }} ctx
+ * @param {typeof import("@clack/prompts")} ui the @clack/prompts module
+ * @param {Helpers} h
+ * @returns {Promise<Record<string, string>>} environment for the wizard process
+ */
+export async function clackSetup(ctx, ui, h) {
+  const wizardConf = ctx.wizardConf;
+  if (ctx.pmMerged) applyConfigEnv(ctx.pmMerged);
+  /** @type {Record<string, string>} */
+  const handoff = {};
+
+  const lemondBase = process.env.LEMOND_BASE || "http://127.0.0.1:13305";
+  handoff.LEMOND_BASE = lemondBase;
+
+  const backendDefault =
+    process.env.PM_BACKEND ||
+    h.envValue(wizardConf, "MEMORY_BACKEND") ||
+    "lemond";
+
+  const backend = await ui.select({
+    message: "Model backend",
+    options: [
+      {
+        value: "lemond",
+        label: "Lemonade (lemond)",
+        hint: "local GGUFs on this host",
+      },
+      {
+        value: "ollama",
+        label: "Ollama",
+        hint: "local models on this host",
+      },
+      {
+        value: "custom",
+        label: "OpenAI-compatible URL",
+        hint: "Meridian, hosted API, other",
+      },
+    ],
+    initialValue: ["lemond", "ollama", "custom"].includes(backendDefault)
+      ? backendDefault
+      : "lemond",
+  });
+  if (ui.isCancel(backend)) {
+    ui.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+
+  let model = "";
+  let apiBase = "";
+  let reflectModel =
+    process.env.PM_REFLECT_MODEL ||
+    machine.PM_REFLECT_MODEL ||
+    h.envValue(wizardConf, "MEMORY_REFLECT_MODEL") ||
+    "";
+
+  if (backend === "lemond") {
+    const spin = ui.spinner();
+    spin.start(`Checking lemond at ${lemondBase}`);
+    const body = await fetchJson(`${lemondBase}/v1/models`);
+    const ids = openAiModelIds(body);
+    spin.stop(
+      body ? `lemond answered (${ids.length} models)` : "lemond not reachable",
+    );
+    if (!body) {
+      ui.log.warn(
+        "Start lemonade (lemond) on this host, or pick custom / Ollama instead.",
+      );
+    }
+    const defaultModel =
+      machine.PM_DEFAULT_MODEL ||
+      machine.MEMORY_MODEL ||
+      h.envValue(wizardConf, "MEMORY_MODEL") ||
+      LEMOND_DEFAULT_MODEL;
+    if (ids.length > 0) {
+      const picked = await ui.select({
+        message: "Retain / consolidate model",
+        options: ids.map((id) => ({ value: id, label: id })),
+        initialValue: ids.includes(defaultModel) ? defaultModel : ids[0],
+      });
+      if (ui.isCancel(picked)) process.exit(0);
+      model = /** @type {string} */ (picked);
+    } else {
+      const typed = await ui.text({
+        message: "Retain / consolidate model id",
+        placeholder: defaultModel,
+        defaultValue: defaultModel,
+      });
+      if (ui.isCancel(typed)) process.exit(0);
+      model = /** @type {string} */ (typed);
+    }
+    apiBase = "http://host.docker.internal:13305/v1";
+  } else if (backend === "ollama") {
+    const ollamaBase = machine.OLLAMA_BASE || "http://127.0.0.1:11434";
+    const spin = ui.spinner();
+    spin.start(`Checking Ollama at ${ollamaBase}`);
+    const body = await fetchJson(`${ollamaBase}/api/tags`);
+    const names = ollamaModelNames(body);
+    spin.stop(
+      body ? `Ollama answered (${names.length} models)` : "Ollama not reachable",
+    );
+    let ollamaInCompose = false;
+    if (!body) {
+      const useDocker = await ui.confirm({
+        message: "Ollama is not on this host. Run it in Docker (compose profile ollama)?",
+        active: "yes",
+        inactive: "no",
+        initialValue: true,
+      });
+      if (ui.isCancel(useDocker)) process.exit(0);
+      ollamaInCompose = Boolean(useDocker);
+      if (ollamaInCompose) {
+        ui.log.info(
+          "LiteLLM will call http://ollama:11434; the wizard pulls the model after the stack starts.",
+        );
+      } else {
+        ui.log.warn(
+          "Start Ollama on this host (OLLAMA_HOST on the Docker bridge), or rerun and pick Docker.",
+        );
+      }
+    }
+    const defaultModel =
+      machine.PM_DEFAULT_MODEL ||
+      machine.MEMORY_MODEL ||
+      h.envValue(wizardConf, "MEMORY_MODEL") ||
+      OLLAMA_DEFAULT_MODEL;
+    if (names.length > 0) {
+      const picked = await ui.select({
+        message: "Retain / consolidate model",
+        options: names.map((n) => ({ value: n, label: n })),
+        initialValue: names.includes(defaultModel) ? defaultModel : names[0],
+      });
+      if (ui.isCancel(picked)) process.exit(0);
+      model = /** @type {string} */ (picked);
+    } else {
+      const typed = await ui.text({
+        message: "Retain / consolidate model",
+        placeholder: defaultModel,
+        defaultValue: defaultModel,
+      });
+      if (ui.isCancel(typed)) process.exit(0);
+      model = /** @type {string} */ (typed);
+    }
+    apiBase = ollamaInCompose ? OLLAMA_COMPOSE_API_BASE : OLLAMA_HOST_API_BASE;
+    if (ollamaInCompose) handoff.MEMORY_OLLAMA_IN_COMPOSE = "1";
+  } else {
+    const defaultBase =
+      machine.CUSTOM_DEFAULT_BASE || "http://host.docker.internal:3456/v1";
+    const defaultModel =
+      machine.CUSTOM_DEFAULT_MODEL ||
+      machine.PM_DEFAULT_MODEL ||
+      h.envValue(wizardConf, "MEMORY_MODEL") ||
+      LEMOND_DEFAULT_MODEL;
+    const baseInput = await ui.text({
+      message: "OpenAI-compatible base URL (host.docker.internal from containers)",
+      placeholder: defaultBase,
+      defaultValue: defaultBase,
+    });
+    if (ui.isCancel(baseInput)) process.exit(0);
+    apiBase = normalizeOpenAiBase(/** @type {string} */ (baseInput));
+
+    const spin = ui.spinner();
+    spin.start("Listing models");
+    const body = await fetchJson(`${apiBase}/models`);
+    const ids = openAiModelIds(body);
+    spin.stop(
+      ids.length
+        ? `Found ${ids.length} models`
+        : "Could not list models (enter id manually)",
+    );
+
+    if (ids.length > 0) {
+      const picked = await ui.select({
+        message: "Retain / consolidate model",
+        options: ids.map((id) => ({ value: id, label: id })),
+        initialValue: ids.includes(defaultModel) ? defaultModel : ids[0],
+      });
+      if (ui.isCancel(picked)) process.exit(0);
+      model = /** @type {string} */ (picked);
+    } else {
+      const typed = await ui.text({
+        message: "Retain / consolidate model id",
+        placeholder: defaultModel,
+        defaultValue: defaultModel,
+      });
+      if (ui.isCancel(typed)) process.exit(0);
+      model = /** @type {string} */ (typed);
+    }
+  }
+
+  const reflectChoice = await ui.select({
+    message: "Reflect model (needs tool calls; used for memory-reflect)",
+    options: [
+      {
+        value: "",
+        label: "Shipped default for this backend",
+        hint: "E4B route on lemond, etc.",
+      },
+      { value: "same", label: "Same as retain model" },
+      { value: "custom", label: "Pick another model id" },
+    ],
+    initialValue: reflectModel ? "custom" : "",
+  });
+  if (ui.isCancel(reflectChoice)) process.exit(0);
+
+  if (reflectChoice === "same") {
+    reflectModel = model;
+  } else if (reflectChoice === "custom") {
+    const typed = await ui.text({
+      message: "Reflect model id",
+      placeholder: model,
+      defaultValue: reflectModel || model,
+    });
+    if (ui.isCancel(typed)) process.exit(0);
+    reflectModel = /** @type {string} */ (typed);
+  } else {
+    reflectModel = "";
+  }
+
+  ui.note("Next: Docker, secrets, indexing, and starting the stack.", "Backend configured");
+
+  handoff.WIZARD_SKIP_BACKEND_STEP = "1";
+  handoff.PM_BACKEND = /** @type {string} */ (backend);
+  handoff.PM_DEFAULT_MODEL = model;
+  handoff.MEMORY_API_BASE = apiBase;
+  handoff.PM_REFLECT_MODEL = reflectModel;
+  return handoff;
+}

package/providers/hindsight/lib/coding-agent.mjs

@@ -0,0 +1,204 @@
+/**
+ * Step "8. Coding-agent plugin", Hindsight half: ensure ~/.hindsight/coding-agent.json
+ * exists (seeded from the tracked template when missing) and check that its optInPaths
+ * cover the indexed roots. Machine-local keys such as notebooklmAccess must live in a
+ * real file — never in the repo template — so we do not replace a materialised config
+ * with a symlink (that used to wipe notebooklmAccess.enabled after step 6).
+ * The meta wizard installs the plugin package itself from the manifest.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { realpathSync } from "node:fs";
+import { installNotebooklmMcp } from "./notebooklm-mcp-install.mjs";
+import { setNotebooklmAccessEnabled } from "../../../wizard/lib/notebooklm-agent-access.mjs";
+import { ensureState } from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+function realpathSafe(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+/** @param {string} filePath */
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** True when notebooklm.yml opts the sync service in. */
+function notebooklmSyncEnabled(ctx) {
+  const yml = ctx.notebookFile || path.join(ctx.home, ".config/hindsight/notebooklm.yml");
+  if (!fs.existsSync(yml)) return false;
+  return /^enabled:\s*true\b/m.test(fs.readFileSync(yml, "utf8"));
+}
+
+/**
+ * Seed or keep a real coding-agent.json. Never leave (or create) a symlink to the shipped
+ * template — machine keys such as notebooklmAccess must not write into the repo.
+ *
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+async function linkAgentConfig(ctx, h) {
+  const rel = ctx.memoryProvider.codingAgent?.configTemplate;
+  if (!rel) return;
+  const target = path.join(ctx.repoRoot, rel);
+  let stat;
+  try {
+    stat = fs.lstatSync(ctx.agentJson);
+  } catch {
+    stat = null;
+  }
+  if (stat?.isSymbolicLink()) {
+    // Copy current contents into a regular file so later writes never hit the template.
+    if (ctx.dry) {
+      h.info(`[dry-run] materialize ${ctx.agentJson} (symlink → regular file)`);
+      return;
+    }
+    const raw = fs.readFileSync(ctx.agentJson, "utf8");
+    fs.unlinkSync(ctx.agentJson);
+    fs.mkdirSync(path.dirname(ctx.agentJson), { recursive: true });
+    fs.writeFileSync(ctx.agentJson, raw.endsWith("\n") ? raw : `${raw}\n`);
+    h.ok(`materialized ${ctx.agentJson} (was symlink → regular file)`);
+    return;
+  }
+  if (stat?.isFile()) {
+    // Keep the real file. Replacing it with a symlink to the shipped template drops
+    // notebooklmAccess.enabled and breaks the NotebookLM MCP on the next Cursor start.
+    h.ok(`${ctx.agentJson} is a machine-local file (not replaced with a symlink)`);
+    return;
+  }
+  // Missing: copy the template into a real file so later notebooklmAccess writes never
+  // land in the repo.
+  if (ctx.dry) {
+    h.info(`[dry-run] create ${ctx.agentJson} from ${rel} (regular file, not a symlink)`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(ctx.agentJson), { recursive: true });
+  const seeded = readJsonSafe(target) || {
+    serverMode: "self-hosted",
+    apiUrl: "http://127.0.0.1:8888",
+    optInOnly: true,
+    optInPaths: [],
+    mapPathToBank: {},
+    notebooklmAccess: { enabled: false, banks: ["*"] },
+  };
+  fs.writeFileSync(ctx.agentJson, `${JSON.stringify(seeded, null, 2)}\n`);
+  h.ok(`created ${ctx.agentJson} from ${rel}`);
+}
+
+/**
+ * If NotebookLM sync is on, keep notebooklmAccess.enabled and the Cursor MCP entry.
+ * Materialises a symlink into a real file first so the flag never writes into the template.
+ *
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+async function ensureNotebooklmAccess(ctx, h) {
+  if (!notebooklmSyncEnabled(ctx)) return;
+  const templatePath = path.join(ctx.repoRoot, "config/coding-agent.json");
+  if (ctx.dry) {
+    h.info(`[dry-run] keep notebooklmAccess.enabled=true (NotebookLM sync is on)`);
+    return;
+  }
+  const result = setNotebooklmAccessEnabled(ctx.agentJson, templatePath, true);
+  h.ok(
+    `notebooklmAccess.enabled=true in ${ctx.agentJson}` +
+      (result.action === "materialized" ? " (materialized symlink → regular file)" : ""),
+  );
+  await installNotebooklmMcp(
+    { home: ctx.home, repoRoot: ctx.repoRoot, agentJson: ctx.agentJson, dry: false },
+    h,
+  );
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ * @returns {string[]}
+ */
+function indexRoots(ctx, h) {
+  const source = fs.existsSync(ctx.indexFile)
+    ? ctx.indexFile
+    : path.join(ctx.repoRoot, "config/index.yml");
+  const roots = [];
+  for (const line of fs.readFileSync(source, "utf8").split("\n")) {
+    const m = line.match(/^\s*- path:\s*"?([^"]+)"?/);
+    if (m) roots.push(h.expandHome(m[1].trim(), ctx.home));
+  }
+  return roots;
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+async function checkOptIn(ctx, h) {
+  // Prefer the live agent config (real file or symlink target). Never write
+  // machine paths into the shipped template unless that is what agentJson resolves to.
+  let target = ctx.agentJson;
+  try {
+    if (fs.lstatSync(ctx.agentJson).isSymbolicLink()) {
+      target = realpathSafe(fs.readlinkSync(ctx.agentJson));
+    }
+  } catch {
+    target = path.join(ctx.repoRoot, "config/coding-agent.json");
+  }
+  if (!fs.existsSync(target)) {
+    target = path.join(ctx.repoRoot, "config/coding-agent.json");
+  }
+  const cfg = JSON.parse(fs.readFileSync(target, "utf8"));
+  if (!Array.isArray(cfg.optInPaths)) cfg.optInPaths = [];
+  const opt = cfg.optInPaths.map((p) => path.resolve(h.expandHome(p, ctx.home)));
+  const missing = [];
+  for (const root of indexRoots(ctx, h)) {
+    const abs = path.resolve(root);
+    const covered = opt.some((p) => abs === p || abs.startsWith(`${p.replace(/\/$/, "")}/`));
+    if (!covered) missing.push(root);
+  }
+  if (!missing.length) {
+    h.ok(`optInPaths in ${target} covers the indexed roots`);
+    return;
+  }
+  h.warn("optInPaths does not cover:");
+  for (const m of missing) h.info(`    ${m}`);
+  if (ctx.dry) {
+    h.info(`[dry-run] offer to add these to optInPaths in ${target}`);
+    return;
+  }
+  const tracked = path.join(ctx.repoRoot, "config/coding-agent.json");
+  const prompt =
+    realpathSafe(target) === realpathSafe(tracked)
+      ? "Add them to optInPaths in the tracked file config/coding-agent.json (shows in git status)?"
+      : `Add them to optInPaths in ${target}?`;
+  if (await h.confirm(ctx, prompt, "n")) {
+    for (const root of missing) {
+      if (!cfg.optInPaths.includes(root)) cfg.optInPaths.push(root);
+    }
+    fs.writeFileSync(target, `${JSON.stringify(cfg, null, 2)}\n`);
+    h.ok(`updated ${target}`);
+  }
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function setupCodingAgent(ctx, h) {
+  ensureState(ctx);
+  await linkAgentConfig(ctx, h);
+  await checkOptIn(ctx, h);
+  // Step 6 may have set notebooklmAccess on a real file; linkAgentConfig used to
+  // symlink over it. Re-assert after linking, then register the MCP.
+  await ensureNotebooklmAccess(ctx, h);
+  if (!notebooklmSyncEnabled(ctx)) {
+    await installNotebooklmMcp(ctx, h);
+  }
+}