@agfpd/iapeer-memory 0.1.1

package/src/commands/verify.ts

@@ -0,0 +1,300 @@
+/**
+ * `iapeer-memory verify [--repair]` — idempotent self-check of the live
+ * surfaces (ADR-010). Cheap by design: any peer's SessionStart health-check
+ * may kick it; the system is repaired by whichever peer is alive, never by
+ * the Index or the human.
+ *
+ * Checks (P1 scope — each lights up as its stage lands):
+ *   1. config            — the package env context resolves (vault exists);
+ *   2. memoryd heartbeat — fresh within the staleness threshold;
+ *   3. notifier watcher  — registration alive          [skip until P3 init];
+ *   4. role doctrines    — rendered version == package version (ADR-010
+ *      marker); `--repair` re-renders from the package templates.
+ *
+ * The roles manifest (`<state>/roles.json`, written by init) names the
+ * roles: `{ "roles": [{ "role", "peerCwd", "template" }] }`. Absent
+ * manifest = init has not run — the doctrine check is skipped, not failed.
+ *
+ * Exit code: 0 — no failures; 1 — at least one check failed (after repair).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import {
+  configFromEnv,
+  renderDoctrine,
+  renderedVersion,
+} from "@agfpd/iapeer-memory-core";
+import { memoryPaths, type MemoryPaths } from "../paths.js";
+import { readRolesManifest } from "../roles.js";
+import { readSlot, writeSlot, SLOT_PROVIDER } from "../slot.js";
+import { packageVersion } from "../version.js";
+import {
+  readWatcherTrigger,
+  registerWatcher,
+  writeLauncherScript,
+  WATCHER_TRIGGER_ID,
+} from "../watcher.js";
+
+/** Heartbeat default is 30s (core memoryd) — 4 missed beats = stale. */
+export const DEFAULT_HEARTBEAT_STALE_MS = 120_000;
+
+export type CheckStatus = "ok" | "fail" | "skip" | "repaired";
+export type CheckResult = { name: string; status: CheckStatus; detail: string };
+
+export type VerifyOptions = {
+  repair?: boolean;
+  paths?: MemoryPaths;
+  version?: string;
+  staleMs?: number;
+  /** Injectable for tests. */
+  nowMs?: number;
+};
+
+type RolesManifest = {
+  roles: Array<{ role: string; peerCwd: string; template: string }>;
+};
+
+export function runVerify(opts: VerifyOptions = {}): CheckResult[] {
+  const repair = opts.repair ?? false;
+  const paths = opts.paths ?? memoryPaths();
+  const version = opts.version ?? packageVersion();
+  const staleMs = opts.staleMs ?? DEFAULT_HEARTBEAT_STALE_MS;
+  const nowMs = opts.nowMs ?? Date.now();
+  const results: CheckResult[] = [];
+
+  // 1. config / env context
+  let configOk = false;
+  try {
+    const config = configFromEnv();
+    configOk = true;
+    results.push({
+      name: "config",
+      status: "ok",
+      detail: `vault ${config.vaultPath} (locale ${config.locale})`,
+    });
+  } catch (err) {
+    results.push({
+      name: "config",
+      status: "fail",
+      detail: `${(err as Error).message} — provision via init (P3) or fill ${paths.configFile}`,
+    });
+  }
+
+  // 1b. memory-provider slot (iapeer memory-slot contract): a provisioned
+  // host must declare the slot; a FOREIGN slot is never repaired over.
+  if (!configOk) {
+    results.push({
+      name: "memory-slot",
+      status: "skip",
+      detail: "not provisioned (config check failed)",
+    });
+  } else {
+    const slot = readSlot(paths.slotPath);
+    if (slot && slot.provider !== SLOT_PROVIDER) {
+      results.push({
+        name: "memory-slot",
+        status: "fail",
+        detail: `slot held by foreign provider "${slot.provider}" — refusing to touch (uninstall it first)`,
+      });
+    } else if (slot && slot.version === version) {
+      results.push({ name: "memory-slot", status: "ok", detail: `declared v${slot.version}` });
+    } else {
+      const problem = slot
+        ? `slot declares v${slot.version}, package is v${version}`
+        : `slot declaration missing at ${paths.slotPath}`;
+      if (!repair) {
+        results.push({ name: "memory-slot", status: "fail", detail: problem });
+      } else {
+        const w = writeSlot({
+          slotPath: paths.slotPath,
+          version,
+          heartbeat: paths.heartbeatPath,
+        });
+        results.push(
+          w.action === "refused-foreign"
+            ? { name: "memory-slot", status: "fail", detail: `${problem}; repair refused — foreign slot` }
+            : { name: "memory-slot", status: "repaired", detail: `${problem} — re-declared v${version}` },
+        );
+      }
+    }
+  }
+
+  // 2. memoryd heartbeat
+  try {
+    const stat = fs.statSync(paths.heartbeatPath);
+    const ageMs = nowMs - stat.mtimeMs;
+    if (ageMs > staleMs) {
+      results.push({
+        name: "memoryd-heartbeat",
+        status: "fail",
+        detail:
+          `stale (${Math.round(ageMs / 1000)}s old, threshold ${Math.round(staleMs / 1000)}s)` +
+          (repair
+            ? " — restart is the notifier watcher's job (registration lands in P3); manual: iapeer-memory memoryd"
+            : ""),
+      });
+    } else {
+      results.push({
+        name: "memoryd-heartbeat",
+        status: "ok",
+        detail: `fresh (${Math.round(ageMs / 1000)}s old)`,
+      });
+    }
+  } catch {
+    results.push({
+      name: "memoryd-heartbeat",
+      status: "fail",
+      detail: `no heartbeat at ${paths.heartbeatPath} — memoryd not running?`,
+    });
+  }
+
+  // 3. notifier watcher registration. The durable trigger lives in the
+  // REGISTRANT's peer profile (canonical storage contract — notifier-runtime
+  // fact, topic memoryd-watcher): registrant = index, whose cwd we know
+  // from the roles manifest. Re-registration is ASYNC (the watcher session
+  // writes the profile on message receipt) — repair reports "sent", a
+  // re-run confirms.
+  {
+    const manifest = readRolesManifest(paths.rolesManifestPath);
+    const indexEntry = manifest?.roles.find((r) => r.role === "index") ?? null;
+    if (!indexEntry) {
+      results.push({
+        name: "notifier-watcher",
+        status: "skip",
+        detail: "roles manifest has no index peer — init has not run",
+      });
+    } else {
+      const trigger = readWatcherTrigger({ registrantCwd: indexEntry.peerCwd });
+      const scriptOk = trigger?.script === paths.launcherPath;
+      if (trigger && scriptOk) {
+        results.push({
+          name: "notifier-watcher",
+          status: "ok",
+          detail: `trigger ${WATCHER_TRIGGER_ID} in index profile → target ${trigger.target ?? "?"}`,
+        });
+      } else {
+        const problem = trigger
+          ? `trigger script is ${trigger.script}, expected ${paths.launcherPath}`
+          : `no ${WATCHER_TRIGGER_ID} trigger in ${indexEntry.peerCwd}/.iapeer/peer-profile.json`;
+        if (!repair) {
+          results.push({ name: "notifier-watcher", status: "fail", detail: problem });
+        } else {
+          writeLauncherScript({
+            launcherPath: paths.launcherPath,
+            binaryPath: paths.binaryPath,
+          });
+          const sent = registerWatcher({ launcherPath: paths.launcherPath });
+          results.push(
+            sent.ok
+              ? {
+                  name: "notifier-watcher",
+                  status: "repaired",
+                  detail: `${problem} — re-registration sent (async; re-run verify to confirm)`,
+                }
+              : {
+                  name: "notifier-watcher",
+                  status: "fail",
+                  detail: `${problem}; re-registration failed — ${sent.detail}`,
+                },
+          );
+        }
+      }
+    }
+  }
+
+  // 4. role doctrine versions (ADR-010 marker)
+  let manifestRaw: string | null = null;
+  try {
+    manifestRaw = fs.readFileSync(paths.rolesManifestPath, "utf-8");
+  } catch {
+    manifestRaw = null;
+  }
+  if (manifestRaw === null) {
+    results.push({
+      name: "role-doctrines",
+      status: "skip",
+      detail: `roles manifest absent (${paths.rolesManifestPath}) — init has not run`,
+    });
+  } else {
+    let manifest: RolesManifest | null = null;
+    try {
+      const parsed = JSON.parse(manifestRaw) as RolesManifest;
+      if (!Array.isArray(parsed.roles)) throw new Error("no roles array");
+      manifest = parsed;
+    } catch (err) {
+      results.push({
+        name: "role-doctrines",
+        status: "fail",
+        detail: `roles manifest unreadable: ${(err as Error).message}`,
+      });
+    }
+    for (const entry of manifest?.roles ?? []) {
+      const name = `doctrine[${entry.role}]`;
+      const target = path.join(entry.peerCwd, ".iapeer", "IAPEER.md");
+      let current: string | null = null;
+      try {
+        current = fs.readFileSync(target, "utf-8");
+      } catch {
+        current = null;
+      }
+      const rendered = current === null ? null : renderedVersion(current);
+      if (current !== null && rendered === version) {
+        results.push({ name, status: "ok", detail: `v${rendered}` });
+        continue;
+      }
+      const problem =
+        current === null
+          ? `doctrine missing at ${target}`
+          : rendered === null
+            ? "no version marker in rendered doctrine"
+            : `v${rendered} != package v${version}`;
+      if (!repair) {
+        results.push({ name, status: "fail", detail: problem });
+        continue;
+      }
+      const outcome = renderDoctrine({
+        templatePath: entry.template,
+        peerCwd: entry.peerCwd,
+        version,
+      });
+      if (outcome.action === "missing-template") {
+        results.push({
+          name,
+          status: "fail",
+          detail: `${problem}; repair failed — template missing at ${entry.template}`,
+        });
+      } else {
+        results.push({
+          name,
+          status: "repaired",
+          detail: `${problem} — re-rendered to v${version}`,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+export function cmdVerify(argv: string[]): number {
+  let repair = false;
+  for (const a of argv) {
+    if (a === "--repair") repair = true;
+    else {
+      console.error(`iapeer-memory verify: unknown flag: ${a}`);
+      return 2;
+    }
+  }
+
+  const results = runVerify({ repair });
+  const width = Math.max(...results.map((r) => r.name.length));
+  for (const r of results) {
+    const mark =
+      r.status === "ok" ? "ok      " :
+      r.status === "repaired" ? "repaired" :
+      r.status === "skip" ? "skip    " : "FAIL    ";
+    console.log(`${mark} ${r.name.padEnd(width)}  ${r.detail}`);
+  }
+  return results.some((r) => r.status === "fail") ? 1 : 0;
+}

package/src/config-env.ts

@@ -0,0 +1,74 @@
+/**
+ * Package config loader — env-format file (`KEY=VALUE`), applied into
+ * `process.env` with CONVENTIONAL precedence:
+ *
+ *     CLI flags  >  process env  >  config file  >  built-in defaults
+ *
+ * i.e. a key already present (non-empty) in the process env is NOT
+ * overwritten by the file. NB: this deliberately diverges from the
+ * MergeMind bootstrap, whose `set -a; source config.env` ran AFTER the
+ * parent env and silently overrode it (documented as a legacy pitfall);
+ * here an operator's explicit `IAPEER_MEMORY_*=` always wins.
+ *
+ * Accepted lines: blank, `# comment`, `KEY=VALUE`, `export KEY=VALUE`.
+ * A VALUE wrapped in matching single or double quotes is unwrapped (one
+ * level, no escape processing — this is a config file, not a shell).
+ */
+
+import fs from "node:fs";
+
+const LINE_RE = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+
+export function parseEnvFile(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const m = LINE_RE.exec(line);
+    if (!m) continue; // not KEY=VALUE — ignored, never a parse failure
+    let value = m[2].trim();
+    if (
+      value.length >= 2 &&
+      (value[0] === '"' || value[0] === "'") &&
+      value.endsWith(value[0])
+    ) {
+      value = value.slice(1, -1);
+    }
+    out[m[1]] = value;
+  }
+  return out;
+}
+
+export type LoadResult = {
+  /** File absent — a valid state (defaults apply), never an error. */
+  missing: boolean;
+  /** Keys applied into the env. */
+  applied: string[];
+  /** Keys present in the file but already set in the env (env wins). */
+  shadowed: string[];
+};
+
+export function loadConfigFile(
+  filePath: string,
+  env: Record<string, string | undefined> = process.env,
+): LoadResult {
+  let text: string;
+  try {
+    text = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return { missing: true, applied: [], shadowed: [] };
+  }
+  const parsed = parseEnvFile(text);
+  const applied: string[] = [];
+  const shadowed: string[] = [];
+  for (const [key, value] of Object.entries(parsed)) {
+    const existing = env[key];
+    if (typeof existing === "string" && existing.length > 0) {
+      shadowed.push(key);
+      continue;
+    }
+    env[key] = value;
+    applied.push(key);
+  }
+  return { missing: false, applied, shadowed };
+}

package/src/paths.ts

@@ -0,0 +1,101 @@
+/**
+ * Host-side path namespace of the package: `~/.iapeer/{state,cache,logs,
+ * plugins}/iapeer-memory/` (convention — docs/09-iapeer-integration.md §2).
+ *
+ * Every root is individually overridable via env (the same keys are valid
+ * `config.env` entries — docs/08 §package config):
+ *
+ * - `IAPEER_MEMORY_CONFIG_FILE` — package config (env format); default
+ *   `~/.iapeer/plugins/iapeer-memory/config.env` (the precedent set by the
+ *   MergeMind plugin config location);
+ * - `IAPEER_MEMORY_STATE_DIR`  — author indexes, heartbeat, detect-hash
+ *   state, roles manifest;
+ * - `IAPEER_MEMORY_CACHE_DIR`  — SQLite index, tags-dictionary mirror;
+ * - `IAPEER_MEMORY_LOGS_DIR`   — log files;
+ * - `IAPEER_MEMORY_DB_PATH`    — SQLite file itself (core config reads the
+ *   same key; the default here mirrors core's `<cacheDir>/index.db`).
+ *
+ * Derived file names are FIXED relative to those roots — one source of
+ * truth for every command (memoryd writes the heartbeat exactly where
+ * verify reads it, by construction).
+ */
+
+import os from "node:os";
+import path from "node:path";
+
+export type MemoryPaths = {
+  configFile: string;
+  stateDir: string;
+  cacheDir: string;
+  logsDir: string;
+  dbPath: string;
+  heartbeatPath: string;
+  hashStatePath: string;
+  tagsMirrorPath: string;
+  /** Roles manifest (written by init, read by verify/render): role → peerCwd/template. */
+  rolesManifestPath: string;
+  /** Rendered author indexes (`<agent>-vault-index.md` + `-full` variant). */
+  indexesDir: string;
+  /** memoryd pid file (written by the CLI memoryd command; uninstall stops by it). */
+  pidPath: string;
+  /**
+   * Memory-provider slot declaration (iapeer memory-slot contract, FINAL):
+   * `~/.iapeer/memory-provider.json` in the STORAGE ROOT (next to the
+   * registry) — written/removed by our init/uninstall, only READ by the core.
+   */
+  slotPath: string;
+  /** Stable compiled CLI binary (hooks/watcher rely on this path). */
+  binaryPath: string;
+  /** Materialised package-owned templates (roles, guide) — see templates/index.ts. */
+  templatesDir: string;
+  /** memoryd launcher — the notifier watcher's script (wraps the stable binary). */
+  launcherPath: string;
+};
+
+export function memoryPaths(
+  env: Record<string, string | undefined> = process.env,
+): MemoryPaths {
+  const home = env.HOME || os.homedir();
+  // IAPEER_ROOT — the ecosystem's ONE storage-root override (fact: iapeer
+  // core constants.ts; its own sandbox tests relocate ~/.iapeer with it).
+  // Respecting it keeps our slot/state co-located with the core's registry
+  // in sandboxes and tests alike.
+  const iapeerDir = env.IAPEER_ROOT || path.join(home, ".iapeer");
+  const stateDir =
+    env.IAPEER_MEMORY_STATE_DIR || path.join(iapeerDir, "state", "iapeer-memory");
+  const cacheDir =
+    env.IAPEER_MEMORY_CACHE_DIR || path.join(iapeerDir, "cache", "iapeer-memory");
+  const logsDir =
+    env.IAPEER_MEMORY_LOGS_DIR || path.join(iapeerDir, "logs", "iapeer-memory");
+  const configFile =
+    env.IAPEER_MEMORY_CONFIG_FILE ||
+    path.join(iapeerDir, "plugins", "iapeer-memory", "config.env");
+  return {
+    configFile,
+    stateDir,
+    cacheDir,
+    logsDir,
+    dbPath: env.IAPEER_MEMORY_DB_PATH || path.join(cacheDir, "index.db"),
+    heartbeatPath: path.join(stateDir, "memoryd.heartbeat"),
+    hashStatePath: path.join(stateDir, "memoryd.hashes.json"),
+    tagsMirrorPath: path.join(cacheDir, "tags-dictionary.md"),
+    rolesManifestPath: path.join(stateDir, "roles.json"),
+    indexesDir: path.join(stateDir, "indexes"),
+    pidPath: path.join(stateDir, "memoryd.pid"),
+    slotPath: path.join(iapeerDir, "memory-provider.json"),
+    binaryPath:
+      env.IAPEER_MEMORY_BINARY_PATH || path.join(home, ".local", "bin", "iapeer-memory"),
+    templatesDir: path.join(path.dirname(configFile), "templates"),
+    launcherPath: path.join(path.dirname(configFile), "memoryd-launcher.sh"),
+  };
+}
+
+/**
+ * Rendered author index file. The basename becomes the section title inside
+ * the layer-5 fragment (context-render uses `path.basename`) — the
+ * `<agent>-vault-index.md` form keeps the visible title parity with the
+ * reference shards.
+ */
+export function authorIndexPath(paths: MemoryPaths, agent: string): string {
+  return path.join(paths.indexesDir, `${agent}-vault-index.md`);
+}

package/src/provision.ts

@@ -0,0 +1,188 @@
+/**
+ * Host provisioning primitives of init (P3a slice): the vault skeleton and
+ * the package config. Both IDEMPOTENT and USER-RESPECTING: existing files
+ * are never overwritten (the config and the 99_System seeds become
+ * operator-owned the moment they exist — docs/10 «пользователь правит,
+ * пакет не перезаписывает»).
+ *
+ * The 99_System seeds are generated from the taxonomy preset in code (one
+ * source of truth with the folder/status tokens) — they are SEEDS, not
+ * templates of ours to maintain: the human/Index grow them afterwards.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type { LocaleId, TaxonomyPreset } from "@agfpd/iapeer-memory-core";
+
+export type ProvisionResult = {
+  createdDirs: string[];
+  createdFiles: string[];
+  kept: string[];
+};
+
+/** 4-field minimal frontmatter — the human's editor template (docs/01). */
+export function draftTemplateContent(taxonomy: TaxonomyPreset): string {
+  return [
+    "---",
+    "title: {{title}}",
+    `status: ${taxonomy.statusTokens.draft}`,
+    "created: {{date}}",
+    "author: {{author}}",
+    "---",
+    "",
+    "",
+  ].join("\n");
+}
+
+/**
+ * Project Overview template seed (ADR-014): the editor template for the
+ * human/Index when starting a project group. Carries the `dir:` field —
+ * the source of truth for the project's working directory.
+ */
+export function overviewTemplateContent(taxonomy: TaxonomyPreset): string {
+  const ru = taxonomy.locale === "ru";
+  const name = ru ? "{{имя}}" : "{{name}}";
+  return [
+    "---",
+    `title: ${taxonomy.projectFiles.overviewPrefix}${name}`,
+    "type: " + (ru ? "проект" : "project"),
+    "tags:",
+    ru ? "  - {{Доменный_Тег}}" : "  - {{Domain_Tag}}",
+    "status: " + (ru ? "активный" : "active"),
+    "created: {{date}}",
+    ru ? "author: {{maintainer латиницей}}" : "author: {{maintainer}}",
+    ru
+      ? "dir: {{абсолютный или ~-относительный путь рабочей папки проекта — источник правды}}"
+      : "dir: {{absolute or ~-relative path to the project's working directory — the source of truth}}",
+    "---",
+    "",
+    `# ${taxonomy.projectFiles.overviewPrefix}${name}`,
+    "",
+    ru
+      ? "Что за проект, цель, текущее состояние верхнего уровня."
+      : "What the project is, its goal, the current top-level state.",
+    "",
+  ].join("\n");
+}
+
+/** Empty tags dictionary seed — the Index grows it (docs/07). */
+export function tagsDictionaryContent(taxonomy: TaxonomyPreset): string {
+  const ru = taxonomy.locale === "ru";
+  return [
+    ru ? "## Доменные теги" : "## Domain tags",
+    "",
+    ru
+      ? "<!-- Канонический список top-level доменных тегов. Ведёт Index; новый домен — строка в таблице. Граница обязательна для пересекающихся доменов. -->"
+      : "<!-- The canonical list of top-level domain tags. Curated by the Index; a new domain = a new table row. The boundary phrase is mandatory for overlapping domains. -->",
+    "",
+    ru ? "| Тег | Граница — про что (опционально) |" : "| Tag | Boundary — what it covers (optional) |",
+    "|---|---|",
+    "",
+  ].join("\n");
+}
+
+/**
+ * Create the vault folder skeleton + 99_System seeds. Returns what was
+ * created vs kept; never deletes or overwrites anything.
+ */
+export function provisionVault(opts: {
+  vaultPath: string;
+  taxonomy: TaxonomyPreset;
+}): ProvisionResult {
+  const { vaultPath, taxonomy } = opts;
+  const createdDirs: string[] = [];
+  const createdFiles: string[] = [];
+  const kept: string[] = [];
+
+  for (const folder of Object.values(taxonomy.folders)) {
+    const dir = path.join(vaultPath, folder);
+    if (fs.existsSync(dir)) {
+      kept.push(folder);
+    } else {
+      fs.mkdirSync(dir, { recursive: true });
+      createdDirs.push(folder);
+    }
+  }
+
+  // The Overview template lives next to the draft template (same Templates/
+  // subfolder, provision-level name — not a taxonomy token: only the seeds
+  // know it, nothing parses it back).
+  const overviewSeedRel = path.join(
+    path.dirname(taxonomy.systemFiles.draftTemplate),
+    `${taxonomy.projectFiles.overviewPrefix.trim()}.md`,
+  );
+  const seeds: Array<[rel: string, content: string]> = [
+    [
+      path.join(taxonomy.folders.system, taxonomy.systemFiles.draftTemplate),
+      draftTemplateContent(taxonomy),
+    ],
+    [
+      path.join(taxonomy.folders.system, taxonomy.systemFiles.tagsDictionary),
+      tagsDictionaryContent(taxonomy),
+    ],
+    [path.join(taxonomy.folders.system, overviewSeedRel), overviewTemplateContent(taxonomy)],
+  ];
+  for (const [rel, content] of seeds) {
+    const file = path.join(vaultPath, rel);
+    if (fs.existsSync(file)) {
+      kept.push(rel);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content, "utf-8");
+    createdFiles.push(rel);
+  }
+
+  return { createdDirs, createdFiles, kept };
+}
+
+export type ConfigContentOptions = {
+  vaultPath: string;
+  locale: LocaleId;
+  human?: string | null;
+  embeddingEndpoint?: string | null;
+  rerankerEndpoint?: string | null;
+};
+
+/** The default package config — operator-owned once written. */
+export function defaultConfigContent(opts: ConfigContentOptions): string {
+  return [
+    "# iapeer-memory package config (env format).",
+    "# Precedence: CLI flags > process env > this file > built-in defaults.",
+    "# This file is operator-owned: the package writes it ONCE at init and",
+    "# never overwrites it (verify/update leave it alone).",
+    "",
+    `IAPEER_MEMORY_VAULT_PATH=${opts.vaultPath}`,
+    `IAPEER_MEMORY_LOCALE=${opts.locale}`,
+    opts.human
+      ? `IAPEER_MEMORY_HUMAN_NAME=${opts.human}`
+      : "# IAPEER_MEMORY_HUMAN_NAME=",
+    "",
+    "# MCP endpoint of memoryd (ADR-012). 8766 = iapeer-MCP neighbour.",
+    "# IAPEER_MEMORY_MCP_PORT=8766",
+    "",
+    "# Search providers (ADR-013). Empty endpoints = BM25-only, a valid state.",
+    opts.embeddingEndpoint
+      ? `IAPEER_MEMORY_EMBEDDING_ENDPOINT=${opts.embeddingEndpoint}`
+      : "# IAPEER_MEMORY_EMBEDDING_ENDPOINT=",
+    "# IAPEER_MEMORY_EMBEDDING_PROVIDER=openai",
+    "# IAPEER_MEMORY_EMBEDDING_MODEL=Qwen/Qwen3-Embedding-8B",
+    opts.rerankerEndpoint
+      ? `IAPEER_MEMORY_RERANKER_ENDPOINT=${opts.rerankerEndpoint}`
+      : "# IAPEER_MEMORY_RERANKER_ENDPOINT=",
+    "# IAPEER_MEMORY_RERANKER_PROVIDER=tei",
+    "",
+    "# Curator personalities exempt from needs_review stamping (ADR-006).",
+    "# IAPEER_MEMORY_CURATOR_SET=index,copywriter,dreamweaver",
+    "",
+  ].join("\n");
+}
+
+export function writeDefaultConfig(
+  opts: ConfigContentOptions & { configFile: string },
+): "written" | "exists" {
+  if (fs.existsSync(opts.configFile)) return "exists";
+  fs.mkdirSync(path.dirname(opts.configFile), { recursive: true });
+  fs.writeFileSync(opts.configFile, defaultConfigContent(opts), "utf-8");
+  return "written";
+}