@bcmyguest/openmem 0.0.0-stage → 0.6.3

package/wizard/bin/pm.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Mise-like task runner for openmem (reads ~/.config/personal-memory/config.toml).
+ *   ./pm configure | up | down | doctor
+ * Packaged installs reach it through `openmem <task>`.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { ensureWizardDeps, resolveWizardRoots } from "../../cli/roots.mjs";
+
+const { pkgRoot, repo: REPO, packaged } = resolveWizardRoots(import.meta.url);
+// setup.mjs is code, so it always comes from the package root, never the stack root.
+const SETUP = path.join(pkgRoot, "wizard/bin/setup.mjs");
+
+const TASKS = {
+  configure: { args: ["--yes"], help: "Full setup and start" },
+  up: { args: ["--up", "--yes"], help: "Start stack" },
+  down: { args: ["--down", "--yes"], help: "Stop stack" },
+  doctor: { args: ["--yes", "--no-smoke"], help: "Validate config (no smoke)" },
+  "install-mcp": {
+    script: "cli/install-memory-mcp.mjs",
+    help: "Install memory MCP servers into ~/.cursor/mcp.json",
+  },
+  "install-coding-agent": {
+    script: "cli/install-coding-agent.mjs",
+    help: "Wire session memory for Claude Code, Codex, OpenCode, Cursor CLI",
+  },
+  "feed-sync": {
+    script: "cli/feed-sync.mjs",
+    help: "Fetch RSS/OpenAlex feeds into index.yml feeds.out_dir",
+  },
+  switch: {
+    script: "cli/switch-memory-provider.mjs",
+    help: "Switch MEMORY_PROVIDER (wizard.conf + optional stack/MCP)",
+  },
+};
+
+const task = process.argv[2];
+if (!task || task === "-h" || task === "--help") {
+  ensureWizardDeps(pkgRoot, packaged);
+  const { loadPmConfig } = await import("../lib/pm-config.mjs");
+  const home = process.env.HOME || "";
+  const { merged } = loadPmConfig(home, REPO);
+  const tasks = /** @type {Record<string, {description?: string}>} */ (
+    merged.tasks || {}
+  );
+  console.log("Usage: pm <task>\n");
+  console.log("Tasks:");
+  for (const name of Object.keys(TASKS)) {
+    const desc = tasks[name]?.description || TASKS[name].help;
+    console.log(`  ${name.padEnd(12)} ${desc}`);
+  }
+  process.exit(task ? 0 : 1);
+}
+
+const spec = TASKS[task];
+if (!spec) {
+  console.error(`unknown task: ${task} (try: ${Object.keys(TASKS).join(", ")})`);
+  process.exit(1);
+}
+
+const extra = process.argv.slice(3);
+
+if (spec.script) {
+  const script = path.join(pkgRoot, spec.script);
+  if (!fs.existsSync(script)) {
+    console.error(`${spec.script} not found; run from a openmem checkout or install`);
+    process.exit(1);
+  }
+  const r = spawnSync(process.execPath, [script, ...extra], {
+    cwd: REPO,
+    stdio: "inherit",
+    env: process.env,
+  });
+  process.exit(r.status ?? 1);
+}
+
+if (!fs.existsSync(SETUP)) {
+  console.error("setup.mjs not found; run from a openmem checkout or install");
+  process.exit(1);
+}
+
+const r = spawnSync(process.execPath, [SETUP, ...spec.args, ...extra], {
+  cwd: REPO,
+  stdio: "inherit",
+  env: process.env,
+});
+if (task === "doctor" && (r.status ?? 1) === 0) {
+  const wiring = spawnSync(process.execPath, [path.join(pkgRoot, "cli/wiring-report.mjs")], {
+    cwd: REPO,
+    stdio: "inherit",
+    env: process.env,
+  });
+  process.exit(wiring.status ?? 0);
+}
+process.exit(r.status ?? 1);

package/wizard/bin/setup.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Setup wizard entry (./setup in a checkout; `openmem setup` when packaged).
+ *
+ * REPO is the mutable stack root (PM_STACK_ROOT, default: the checkout): compose project
+ * dir, .env, generated files and docker build context. PM_PACKAGE_ROOT is the read-only
+ * code root (providers/, scripts/setup.mjs, wizard/lib).
+ */
+import { ensureWizardDeps, resolveWizardRoots } from "../../cli/roots.mjs";
+
+const { pkgRoot, repo: REPO, packaged } = resolveWizardRoots(import.meta.url);
+ensureWizardDeps(pkgRoot, packaged);
+
+const { runWizard } = await import("../lib/run-wizard.mjs");
+
+const argv = process.argv.slice(2);
+const wantsClack =
+  !argv.includes("--yes") &&
+  !argv.includes("-y") &&
+  !argv.includes("--dry-run") &&
+  process.stdin.isTTY;
+
+/** @type {Record<string, string>} */
+let handoff = {};
+if (wantsClack) {
+  const { runClackSetup } = await import("../lib/run-clack.mjs");
+  handoff = await runClackSetup(REPO);
+  for (const [k, v] of Object.entries(handoff)) {
+    process.env[k] = v;
+  }
+}
+
+await runWizard(REPO, argv);

package/wizard/lib/compose-version.mjs

@@ -0,0 +1,32 @@
+/**
+ * Docker Compose version gate for the wizard preflight.
+ *
+ * Provider compose fragments use `env_file: [{path, required: false}]`, which needs Compose 2.24;
+ * the Hindsight base file already needs 2.20 for `depends_on.required`. The wizard requires the
+ * higher bar everywhere so a stack never fails halfway through `docker compose up`.
+ */
+
+export const MIN_COMPOSE = { major: 2, minor: 24 };
+
+/**
+ * Parse `docker compose version --short` ("2.29.0", "v2.29.0") or the long form
+ * ("Docker Compose version v2.29.0"). Returns null when no version is found.
+ * @param {string} text
+ * @returns {{major:number, minor:number}|null}
+ */
+export function parseComposeVersion(text) {
+  const m = String(text || "").match(/v?(\d+)\.(\d+)/);
+  return m ? { major: Number(m[1]), minor: Number(m[2]) } : null;
+}
+
+/**
+ * @param {{major:number, minor:number}|null} version
+ * @returns {boolean} true when the version meets MIN_COMPOSE
+ */
+export function composeVersionOk(version) {
+  if (!version) return false;
+  if (version.major !== MIN_COMPOSE.major) return version.major > MIN_COMPOSE.major;
+  return version.minor >= MIN_COMPOSE.minor;
+}
+
+export const COMPOSE_TOO_OLD_HINT = `Docker Compose ${MIN_COMPOSE.major}.${MIN_COMPOSE.minor} or newer is required (docker compose version --short); provider compose files use env_file required: false. Update the compose plugin`;

package/wizard/lib/compose.mjs

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Compose profiles for the active provider + optional extras (Ollama, NotebookLM).
+ *
+ * @param {{ memoryProvider?: { compose?: { profile?: string } }, extraComposeProfiles?: string[] }} ctx
+ * @returns {string[]}
+ */
+export function composeProfiles(ctx) {
+  const compose = ctx.memoryProvider?.compose || {};
+  const profiles = [];
+  if (compose.profile) profiles.push(compose.profile);
+  for (const p of ctx.extraComposeProfiles || []) {
+    if (typeof p === "string" && p && !profiles.includes(p)) profiles.push(p);
+  }
+  return profiles;
+}
+
+/**
+ * Arguments for `docker` that run a compose subcommand for the active provider.
+ *
+ * Every compose call in the wizard goes through here so the manifest's
+ * `compose.profile` and `compose.files` apply uniformly (up, build, run, down, ps).
+ * With no `compose.files`, no -f flag is added and compose auto-loads compose.yaml
+ * and compose.override.yaml from the stack root. With `compose.files`, the list is
+ * compose.yaml, compose.override.yaml (when present), then the extra files.
+ *
+ * Extra profiles (compose Ollama, NotebookLM) come from `ctx.extraComposeProfiles`.
+ * Docker Compose unions CLI `--profile` with `COMPOSE_PROFILES` from `.env`, so
+ * `composeSpawnOptions` overrides that env var to the same list — otherwise `.env`
+ * can start NotebookLM while the wizard intentionally omitted it (e.g. during smoke).
+ *
+ * @param {{ project: string, repoRoot: string, memoryProvider?: { compose?: { profile?: string, files?: string[] } }, extraComposeProfiles?: string[] }} ctx
+ * @param {...string} rest the compose subcommand and its arguments
+ * @returns {string[]}
+ */
+export function composeArgs(ctx, ...rest) {
+  const compose = ctx.memoryProvider?.compose || {};
+  const args = ["compose", "-p", ctx.project];
+  const extra = Array.isArray(compose.files) ? compose.files : [];
+  if (extra.length) {
+    args.push("-f", "compose.yaml");
+    if (fs.existsSync(path.join(ctx.repoRoot, "compose.override.yaml"))) {
+      args.push("-f", "compose.override.yaml");
+    }
+    for (const f of extra) args.push("-f", f);
+  }
+  for (const p of composeProfiles(ctx)) args.push("--profile", p);
+  return [...args, ...rest];
+}
+
+/** `docker ...` as the wizard prints it in descriptions. */
+export function composeCommandText(ctx, ...rest) {
+  return `docker ${composeArgs(ctx, ...rest).join(" ")}`;
+}
+
+/**
+ * Spawn options for compose calls: cwd is the stack root; COMPOSE_PROFILES matches
+ * the `--profile` flags so `.env` cannot enable extra profiles behind the wizard's back.
+ */
+export function composeSpawnOptions(ctx) {
+  return {
+    cwd: ctx.repoRoot,
+    env: {
+      ...process.env,
+      COMPOSE_PROFILES: composeProfiles(ctx).join(","),
+    },
+  };
+}

package/wizard/lib/curl.mjs

@@ -0,0 +1,103 @@
+import { spawn, spawnSync } from "node:child_process";
+
+/**
+ * @param {string} url
+ * @param {number} [timeoutSec]
+ * @returns {string}
+ */
+export function curlGet(url, timeoutSec = 5) {
+  const r = spawnSync("curl", ["-fsS", "-m", String(timeoutSec), url], {
+    encoding: "utf8",
+  });
+  if (r.status !== 0) return "";
+  return r.stdout || "";
+}
+
+/**
+ * @param {string} url
+ * @returns {object|null}
+ */
+export function curlJson(url) {
+  const body = curlGet(url);
+  if (!body) return null;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} method
+ * @param {string} url
+ * @param {string} [jsonBody]
+ * @param {number} [timeoutSec]
+ * @returns {string}
+ */
+export function curlRequest(method, url, jsonBody, timeoutSec = 60) {
+  const args = curlArgs(method, url, jsonBody, timeoutSec);
+  const r = spawnSync("curl", args, { encoding: "utf8" });
+  if (r.status !== 0) return "";
+  return r.stdout || "";
+}
+
+/**
+ * Build curl argv for a JSON (or empty-body) request.
+ * @param {string} method
+ * @param {string} url
+ * @param {string} [jsonBody]
+ * @param {number} timeoutSec
+ * @returns {string[]}
+ */
+export function curlArgs(method, url, jsonBody, timeoutSec) {
+  const args = ["-fsS", "-m", String(timeoutSec), "-X", method, url];
+  if (jsonBody !== undefined) {
+    args.push("-H", "Content-Type: application/json", "-d", jsonBody);
+  }
+  return args;
+}
+
+/**
+ * Like curlRequest, but async with an optional heartbeat so long retains do not look hung.
+ *
+ * @param {string} method
+ * @param {string} url
+ * @param {string} [jsonBody]
+ * @param {number} [timeoutSec]
+ * @param {{ tickSec?: number, onTick?: (info: { elapsed: number, timeoutSec: number }) => void }} [opts]
+ * @returns {Promise<string>} response body, or "" on failure / timeout
+ */
+export function curlRequestProgress(method, url, jsonBody, timeoutSec = 60, opts = {}) {
+  const tickSec = opts.tickSec ?? 15;
+  const onTick = opts.onTick;
+  const args = curlArgs(method, url, jsonBody, timeoutSec);
+  return new Promise((resolve) => {
+    const child = spawn("curl", args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let settled = false;
+    const started = Date.now();
+    const timer =
+      typeof onTick === "function"
+        ? setInterval(() => {
+            onTick({
+              elapsed: Math.round((Date.now() - started) / 1000),
+              timeoutSec,
+            });
+          }, tickSec * 1000)
+        : null;
+
+    const finish = (body) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearInterval(timer);
+      resolve(body);
+    };
+
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.on("error", () => finish(""));
+    child.on("close", (code) => finish(code === 0 ? stdout : ""));
+  });
+}

package/wizard/lib/docker-build.mjs

@@ -0,0 +1,148 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { ok, die } from "./log.mjs";
+import { act } from "./exec.mjs";
+import { composeArgs, composeSpawnOptions } from "./compose.mjs";
+
+function buildDockerfile(svc) {
+  if (svc === "indexer") return "indexer/Dockerfile";
+  if (svc === "notebooklm") return "sync/Dockerfile";
+  die(`the wizard does not build service ${svc}`);
+}
+
+function copySourcesFromDockerfile(repoRoot, dfRel) {
+  const dfPath = path.join(repoRoot, dfRel);
+  const text = fs.readFileSync(dfPath, "utf8");
+  const srcs = [];
+  for (const line of text.split("\n")) {
+    if (!line.startsWith("COPY")) continue;
+    const parts = line.trim().split(/\s+/).slice(1);
+    const filtered = parts.filter((p) => !p.startsWith("--"));
+    for (let i = 0; i < filtered.length - 1; i++) srcs.push(filtered[i]);
+  }
+  return srcs;
+}
+
+function expandInputs(repoRoot, rel) {
+  const abs = path.join(repoRoot, rel);
+  const out = [];
+  if (!fs.existsSync(abs)) {
+    out.push(rel);
+    return out;
+  }
+  if (fs.statSync(abs).isDirectory()) {
+    const walk = (dir, prefix) => {
+      for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (ent.name === "__pycache__" || ent.name.endsWith(".pyc")) continue;
+        const p = path.join(dir, ent.name);
+        const relP = prefix ? `${prefix}/${ent.name}` : ent.name;
+        if (ent.isDirectory()) walk(p, relP);
+        else out.push(relP);
+      }
+    };
+    walk(abs, rel);
+  } else out.push(rel);
+  return out;
+}
+
+/**
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} svc
+ */
+export function buildHash(ctx, svc) {
+  const df = buildDockerfile(svc);
+  const files = new Set([df, "compose.yaml"]);
+  for (const f of ctx.memoryProvider?.compose?.files || []) files.add(f);
+  for (const src of copySourcesFromDockerfile(ctx.repoRoot, df)) {
+    for (const f of expandInputs(ctx.repoRoot, src)) files.add(f);
+  }
+  const sorted = [...files].sort();
+  const hash = crypto.createHash("sha256");
+  for (const f of sorted) {
+    const p = path.join(ctx.repoRoot, f);
+    if (!fs.existsSync(p)) die(`missing build input ${f}`);
+    hash.update(fs.readFileSync(p));
+  }
+  return hash.digest("hex");
+}
+
+/**
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} svc
+ * @param {string} hash
+ */
+function recordBuildHash(ctx, svc, hash) {
+  let lines = [];
+  if (fs.existsSync(ctx.buildHashFile)) {
+    lines = fs
+      .readFileSync(ctx.buildHashFile, "utf8")
+      .split("\n")
+      .filter((l) => l && !l.startsWith(`${svc} `));
+  }
+  lines.push(`${svc} ${hash}`);
+  fs.writeFileSync(ctx.buildHashFile, `${lines.join("\n")}\n`);
+}
+
+/**
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} svc
+ * @param {string} image
+ */
+export async function buildService(ctx, svc, image) {
+  const hash = buildHash(ctx, svc);
+  let stored = "";
+  if (fs.existsSync(ctx.buildHashFile)) {
+    for (const line of fs.readFileSync(ctx.buildHashFile, "utf8").split("\n")) {
+      if (line.startsWith(`${svc} `)) stored = line.split(/\s+/)[1] || "";
+    }
+  }
+  const inspect = spawnSync("docker", ["image", "inspect", image], { stdio: "ignore" });
+  const imageOk = inspect.status === 0;
+  if (!ctx.rebuild && stored === hash && imageOk) {
+    ok(`${svc} image unchanged; build skipped`);
+    return;
+  }
+  await act(
+    ctx,
+    `build the ${svc} image (compose project ${ctx.project})`,
+    "docker",
+    composeArgs(ctx, "build", svc),
+    composeSpawnOptions(ctx),
+  );
+  if (ctx.dry) return;
+  recordBuildHash(ctx, svc, hash);
+}
+
+/**
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @returns {Promise<string[]>}
+ */
+export async function snapshot(ctx) {
+  const lines = [];
+  const globHs = fs.existsSync(ctx.hsDir) ? fs.readdirSync(ctx.hsDir) : [];
+  for (const name of globHs) {
+    const f = path.join(ctx.hsDir, name);
+    if (fs.statSync(f).isFile()) {
+      const h = crypto.createHash("sha256").update(fs.readFileSync(f)).digest("hex");
+      lines.push(`${f} ${h}`);
+    }
+  }
+  for (const f of [path.join(ctx.repoRoot, ".env"), path.join(ctx.repoRoot, "compose.override.yaml")]) {
+    if (fs.existsSync(f)) {
+      const h = crypto.createHash("sha256").update(fs.readFileSync(f)).digest("hex");
+      lines.push(`${f} ${h}`);
+    }
+  }
+  const ps = spawnSync("docker", composeArgs(ctx, "ps", "-q"), {
+    encoding: "utf8",
+    ...composeSpawnOptions(ctx),
+  });
+  if (ps.status === 0 && ps.stdout) {
+    for (const id of ps.stdout.split("\n").filter(Boolean)) {
+      lines.push(`container ${id.trim()}`);
+    }
+  }
+  return lines.sort();
+}

package/wizard/lib/exec.mjs

@@ -0,0 +1,41 @@
+import { spawnSync } from "node:child_process";
+import { info } from "./log.mjs";
+
+/**
+ * Run a command, or print it when the context is a dry run. Exits the process on failure.
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} description
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ env?: Record<string, string>, cwd?: string }} [opts] extra environment, working directory
+ */
+export async function act(ctx, description, cmd, args, opts = {}) {
+  if (ctx.dry) {
+    info(`[dry-run] ${description}`);
+    return;
+  }
+  info(description);
+  const r = spawnSync(cmd, args, {
+    stdio: "inherit",
+    env: { ...process.env, ...(opts.env || {}) },
+    ...(opts.cwd ? { cwd: opts.cwd } : {}),
+  });
+  if (r.status !== 0) process.exit(r.status ?? 1);
+}
+
+/**
+ * Like act(), with extra environment variables for the child.
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} description
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {Record<string, string>} extraEnv
+ */
+export async function actWithEnv(ctx, description, cmd, args, extraEnv) {
+  await act(ctx, description, cmd, args, { env: extraEnv });
+}
+
+export function commandExists(name) {
+  const r = spawnSync("command", ["-v", name], { shell: true, stdio: "ignore" });
+  return r.status === 0;
+}

package/wizard/lib/indexer.mjs

@@ -0,0 +1,6 @@
+/**
+ * The shared indexer's container entry point. The wizard runs it with --list to preview
+ * which sources an index.yml selects. PM_INDEXER_BIN overrides the name if the entry
+ * point is renamed.
+ */
+export const INDEXER_BIN = process.env.PM_INDEXER_BIN || "hindsight-project-index";

package/wizard/lib/load-machine-env.mjs

@@ -0,0 +1,4 @@
+/** @deprecated Use ~/.config/personal-memory/config.toml. Kept for provider hook compatibility. */
+export function loadMachineEnv(_repoRoot) {
+  return {};
+}

package/wizard/lib/log.mjs

@@ -0,0 +1,32 @@
+const tty = Boolean(process.stdout.isTTY);
+const BOLD = tty ? "\x1b[1m" : "";
+const GREEN = tty ? "\x1b[32m" : "";
+const YELLOW = tty ? "\x1b[33m" : "";
+const RED = tty ? "\x1b[31m" : "";
+const RESET = tty ? "\x1b[0m" : "";
+
+export function step(title) {
+  console.log(`\n${BOLD}== ${title} ==${RESET}`);
+}
+
+export function info(msg) {
+  console.log(`  ${msg}`);
+}
+
+export function ok(msg) {
+  console.log(`  ${GREEN}ok${RESET} ${msg}`);
+}
+
+export function warn(msg) {
+  console.error(`  ${YELLOW}warn${RESET} ${msg}`);
+}
+
+export function die(msg) {
+  console.error(`  ${RED}error${RESET} ${msg}`);
+  process.exit(1);
+}
+
+export function problem(ctx, msg) {
+  if (ctx.dry) warn(`${msg} (dry run: continuing)`);
+  else die(msg);
+}

package/wizard/lib/notebooklm-agent-access.mjs

@@ -0,0 +1,92 @@
+/**
+ * Opt-in coding-agent NotebookLM MCP access: materialize ~/.hindsight/coding-agent.json
+ * as a real file (never write machine settings into the repo template) and toggle
+ * notebooklmAccess.enabled.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * @param {string} agentPath ~/.hindsight/coding-agent.json
+ * @param {string} templatePath repo config/coding-agent.json
+ * @returns {{ path: string, action: "created" | "materialized" | "exists", cfg: Record<string, any> }}
+ */
+export function ensureCodingAgentJsonRealFile(agentPath, templatePath) {
+  fs.mkdirSync(path.dirname(agentPath), { recursive: true });
+
+  let stat = null;
+  try {
+    stat = fs.lstatSync(agentPath);
+  } catch {
+    stat = null;
+  }
+
+  if (stat?.isSymbolicLink()) {
+    const raw = fs.readFileSync(agentPath, "utf8");
+    const cfg = JSON.parse(raw);
+    fs.unlinkSync(agentPath);
+    fs.writeFileSync(agentPath, `${JSON.stringify(cfg, null, 2)}\n`);
+    return { path: agentPath, action: "materialized", cfg };
+  }
+
+  if (stat?.isFile()) {
+    const cfg = JSON.parse(fs.readFileSync(agentPath, "utf8"));
+    return { path: agentPath, action: "exists", cfg };
+  }
+
+  let cfg;
+  if (fs.existsSync(templatePath) && fs.statSync(templatePath).isFile()) {
+    cfg = JSON.parse(fs.readFileSync(templatePath, "utf8"));
+  } else {
+    cfg = {
+      serverMode: "self-hosted",
+      apiUrl: "http://127.0.0.1:8888",
+      optInOnly: true,
+      optInPaths: [],
+      mapPathToBank: {},
+      notebooklmAccess: { enabled: false, banks: ["*"] },
+    };
+  }
+  fs.writeFileSync(agentPath, `${JSON.stringify(cfg, null, 2)}\n`);
+  return { path: agentPath, action: "created", cfg };
+}
+
+/**
+ * Set notebooklmAccess.enabled on a real coding-agent.json. Never writes templatePath.
+ * Materializes a symlink into a regular file first when needed.
+ *
+ * @param {string} agentPath
+ * @param {string} templatePath
+ * @param {boolean} enabled
+ * @param {{ dry?: boolean }} [opts]
+ * @returns {{ dry?: boolean, action?: string, agentPath: string, enabled: boolean, wrote: boolean }}
+ */
+export function setNotebooklmAccessEnabled(agentPath, templatePath, enabled, opts = {}) {
+  const absTemplate = path.resolve(templatePath);
+  if (opts.dry) {
+    return {
+      dry: true,
+      agentPath,
+      enabled,
+      wrote: false,
+      action: fs.existsSync(agentPath)
+        ? fs.lstatSync(agentPath).isSymbolicLink()
+          ? "would-materialize"
+          : "would-update"
+        : "would-create",
+    };
+  }
+
+  const { cfg, action } = ensureCodingAgentJsonRealFile(agentPath, templatePath);
+  // Guard: never write into the shipped template even if agentPath somehow resolves there.
+  if (path.resolve(agentPath) === absTemplate) {
+    throw new Error(`refusing to write notebooklmAccess into shipped template ${templatePath}`);
+  }
+  const access =
+    cfg.notebooklmAccess && typeof cfg.notebooklmAccess === "object" ? { ...cfg.notebooklmAccess } : {};
+  access.enabled = enabled === true;
+  if (!Array.isArray(access.banks) || !access.banks.length) access.banks = ["*"];
+  cfg.notebooklmAccess = access;
+  fs.writeFileSync(agentPath, `${JSON.stringify(cfg, null, 2)}\n`);
+  return { agentPath, enabled: access.enabled, wrote: true, action };
+}