@cerefox/memory 1.7.0 → 1.7.1

package/AGENT_GUIDE.md

@@ -478,7 +478,7 @@ Call `cerefox_list_metadata_keys` for the current list -- conventions evolve.
 
 ## Writing linkable content
 
-Documents you ingest may contain markdown links to other Cerefox documents. The Cerefox web UI intercepts these links at click time and resolves them to the target document. The resolution happens entirely in the browser; the stored markdown is untouched.
+Documents you ingest may contain markdown links to other Cerefox documents. The Cerefox web UI intercepts these links at click time and resolves them to the target document. The resolution happens entirely in the browser; the stored markdown is untouched. (User-facing overview of the whole linking system, including *why* long ids corrupt during regeneration: [`docs/guides/linking.md`](docs/guides/linking.md).)
 
 ### The rule for agents: use document UUIDs
 
@@ -502,9 +502,9 @@ same-turn-fixable error. Three things to know:
   mechanism, and it is just correct markdown authoring.
 - **Only links your write introduces are validated on updates.** A dead
   link the document already carried (its target purged after linking) does
-  not block your unrelated edit — legacy dead links are found by the
-  dead-link sweep (#214 phase 2), not by holding your edit hostage. New
-  documents validate every link.
+  not block your unrelated edit — legacy dead links are found on demand by
+  the sweep (`cerefox document dead-links`, CLI), not by holding your edit
+  hostage. New documents validate every link.
 
 `[[Wikilinks]]` are NOT validated — they remain the sanctioned form for
 "flag a document to create later."

package/dist/bin/cerefox.js

@@ -7438,7 +7438,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "1.7.0";
+var PKG_VERSION = "1.7.1";
 var init_meta = () => {};
 
 // ../../_shared/config/paths.ts
@@ -25743,7 +25743,7 @@ var init_bundled_docs = __esm(() => {
 });
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "1.7.0", CEREFOX_VERSION = "1.7.0", EF_LAST_CHANGED = "1.7.0";
+var EF_VERSION = "1.7.1", CEREFOX_VERSION = "1.7.1", EF_LAST_CHANGED = "1.7.0";
 var init_ef_meta = () => {};
 
 // ../../_shared/compatibility/index.ts
@@ -41592,10 +41592,10 @@ var require_flate = __commonJS((exports) => {
   var GenericWorker = require_GenericWorker();
   var ARRAY_TYPE = USE_TYPEDARRAY ? "uint8array" : "array";
   exports.magic = "\b\x00";
-  function FlateWorker(action19, options) {
-    GenericWorker.call(this, "FlateWorker/" + action19);
+  function FlateWorker(action20, options) {
+    GenericWorker.call(this, "FlateWorker/" + action20);
     this._pako = null;
-    this._pakoAction = action19;
+    this._pakoAction = action20;
     this._pakoOptions = options;
     this.meta = {};
   }
@@ -57699,11 +57699,11 @@ async function runSyncSelfDocs(options = {}) {
     printTable(outcomes.filter((o) => o.status === "error").map((o) => ({ topic: o.topic, error: o.detail.slice(0, 100) })));
   }
 }
-async function action21(options) {
+async function action22(options) {
   await runSyncSelfDocs(options);
 }
 function registerSyncSelfDocs(program2) {
-  program2.command("sync-self-docs").description("Ingest bundled Cerefox docs under the _cerefox-self-docs project.").option("--dry-run", "List what would be ingested without writing.").option("--project <name>", "Override the target project name.", "_cerefox-self-docs").action(action21);
+  program2.command("sync-self-docs").description("Ingest bundled Cerefox docs under the _cerefox-self-docs project.").option("--dry-run", "List what would be ingested without writing.").option("--project <name>", "Override the target project name.", "_cerefox-self-docs").action(action22);
 }
 var init_sync_self_docs = __esm(() => {
   init_cli_core();
@@ -72797,11 +72797,48 @@ function registerDeleteDoc(program2) {
   program2.command("delete-doc").description("Soft-delete a document (recoverable via the web UI trash).").argument("<document-id>", "UUID of the document to delete.").option("--reason <text>", "Optional reason recorded in the audit log.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").option("--yes", "Skip the confirmation prompt.").action(action7);
 }
 
+// src/cli/commands/document-dead-links.ts
+init_cli_core();
+init_client();
+var SERVER_BEHIND = "The sweep did not run: this server has no cerefox_find_dead_links (needs schema 0.12.2). " + "Run `cerefox server deploy`, then retry.";
+async function action8(options) {
+  const client = getClient();
+  let rows;
+  try {
+    rows = await client.rpc("cerefox_find_dead_links", {});
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    if (isMissingFunctionError(message, "cerefox_find_dead_links")) {
+      throw systemError(SERVER_BEHIND);
+    }
+    throw e;
+  }
+  if (rows === null)
+    throw systemError(SERVER_BEHIND);
+  if (options.json) {
+    printJson(rows);
+    return;
+  }
+  if (rows.length === 0) {
+    println(c.green("✓ No dead document links found."));
+    return;
+  }
+  println(c.yellow(`${rows.length} dead link(s) across ${new Set(rows.map((r) => r.document_id)).size} document(s):`));
+  for (const r of rows) {
+    println(`  ${r.document_title} (${r.document_id})`);
+    println(c.dim(`    → [Text](${r.dead_link_id}) ×${r.occurrences} — target no longer exists`));
+  }
+  println(c.dim(`Fix each by editing the linking document (correct the id, remove the link, or backtick it as an example). ` + `The write-time guard prevents NEW dead links; these predate it or lost their target to a purge.`));
+}
+function registerDocumentDeadLinks(program2) {
+  program2.command("dead-links").description("Find [Text](uuid) links whose target document no longer exists (#214 phase 2).").option("--json", "Machine-readable output.").action(action8);
+}
+
 // src/cli/commands/delete-project.ts
 init_cli_core();
 init_client();
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-async function action8(target, options) {
+async function action9(target, options) {
   const client = getClient();
   const isUuid = UUID_RE.test(target);
   const lookup = isUuid ? client.raw.from("cerefox_projects").select("id, name, description").eq("id", target).maybeSingle() : client.raw.from("cerefox_projects").select("id, name, description").eq("name", target).maybeSingle();
@@ -72837,7 +72874,7 @@ async function action8(target, options) {
   println(c.green(`✓ Deleted project "${project.name}" (id: ${project.id}).`));
 }
 function registerDeleteProject(program2) {
-  program2.command("delete-project").description("Delete an empty project (use --force to remove a non-empty one).").argument("<name-or-id>", "Project name (exact match) or UUID.").option("--yes", "Skip the confirmation prompt.").option("--force", "Allow deletion when documents are still linked to the project.").action(action8);
+  program2.command("delete-project").description("Delete an empty project (use --force to remove a non-empty one).").argument("<name-or-id>", "Project name (exact match) or UUID.").option("--yes", "Skip the confirmation prompt.").option("--force", "Allow deletion when documents are still linked to the project.").action(action9);
 }
 
 // src/cli/commands/deploy-server.ts
@@ -73043,7 +73080,7 @@ function listEdgeFunctions(functionsDir) {
     return [];
   return readdirSync2(functionsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && e.name.startsWith("cerefox-")).map((e) => e.name).sort();
 }
-async function action9(options) {
+async function action10(options) {
   const settings = loadSettings();
   const assets = resolveServerAssets();
   const doSchema = !options.functionsOnly;
@@ -73258,7 +73295,7 @@ Proceed with deployment to Supabase?`, true);
   println(c.dim("Verify with: cerefox doctor"));
 }
 function registerDeployServer(program2) {
-  program2.command("deploy-server").description("Deploy/update the Cerefox server side (schema + RPCs + Edge Functions) on Supabase.").option("--dry-run", "Print the plan + pre-flight without deploying.").option("--schema-only", "Deploy/update only the schema + RPCs (skip Edge Functions).").option("--functions-only", "Deploy only the Edge Functions (skip the schema/RPCs).").option("--project-ref <ref>", "Supabase project ref for Edge Function deploys (default: derived from CEREFOX_SUPABASE_URL).").option("--yes", "Non-interactive (skip the deployment confirmation).").action(action9);
+  program2.command("deploy-server").description("Deploy/update the Cerefox server side (schema + RPCs + Edge Functions) on Supabase.").option("--dry-run", "Print the plan + pre-flight without deploying.").option("--schema-only", "Deploy/update only the schema + RPCs (skip Edge Functions).").option("--functions-only", "Deploy only the Edge Functions (skip the schema/RPCs).").option("--project-ref <ref>", "Supabase project ref for Edge Function deploys (default: derived from CEREFOX_SUPABASE_URL).").option("--yes", "Non-interactive (skip the deployment confirmation).").action(action10);
 }
 
 // src/cli/commands/document-edit.ts
@@ -73278,7 +73315,7 @@ function parseMetaPair(pair) {
   }
   return [key, value];
 }
-async function action10(documentId, options) {
+async function action11(documentId, options) {
   const hasTitle = options.title !== undefined;
   const sets = options.setMeta ?? [];
   const unsets = options.unsetMeta ?? [];
@@ -73296,18 +73333,41 @@ async function action10(documentId, options) {
   if (doc.deleted_at) {
     throw userError(`Document ${documentId} is soft-deleted — restore it first (cerefox document restore).`);
   }
-  const metadata = { ...doc.metadata ?? {} };
-  for (const pair of sets) {
-    const [k, v] = parseMetaPair(pair);
-    metadata[k] = v;
-  }
-  for (const k of unsets)
-    delete metadata[k.trim()];
+  const metaTouched = sets.length > 0 || unsets.length > 0;
   const newTitle = hasTitle ? options.title.trim() : doc.title;
   const titleChanged = newTitle !== doc.title;
-  const { error: updErr } = await client.raw.from("cerefox_documents").update({ title: newTitle, metadata, updated_at: new Date().toISOString() }).eq("id", documentId);
-  if (updErr)
-    throw systemError(`Update failed: ${updErr.message}`);
+  const author = resolveAuthor(options.author);
+  const authorType = resolveAuthorType(options.authorType);
+  if (author === "unknown") {
+    warn("No --author / CEREFOX_AUTHOR_NAME set — audit log will record this write as 'unknown'.");
+  }
+  if (metaTouched) {
+    const patch = {};
+    for (const pair of sets) {
+      const [k, v] = parseMetaPair(pair);
+      patch[k] = v;
+    }
+    for (const k of unsets)
+      patch[k.trim()] = null;
+    const { error: metaErr } = await client.raw.rpc("cerefox_set_document_metadata", {
+      p_document_id: documentId,
+      p_metadata: patch,
+      p_replace: false,
+      p_author: author,
+      p_author_type: authorType
+    });
+    if (metaErr) {
+      if (metaErr.message?.includes("CEREFOX_BAD_METADATA")) {
+        throw userError(`Document ${documentId} has non-object metadata; a patch cannot repair it. ` + `Repair it first with: cerefox document set-metadata ${documentId} --replace --json '<the intended object>'`);
+      }
+      throw systemError(`Metadata update failed: ${metaErr.message}`);
+    }
+  }
+  if (hasTitle) {
+    const { error: updErr } = await client.raw.from("cerefox_documents").update({ title: newTitle, updated_at: new Date().toISOString() }).eq("id", documentId);
+    if (updErr)
+      throw systemError(`Update failed: ${updErr.message}`);
+  }
   if (titleChanged) {
     const { error: ftsErr } = await client.raw.rpc("cerefox_update_chunk_fts", {
       p_document_id: documentId,
@@ -73316,18 +73376,15 @@ async function action10(documentId, options) {
     if (ftsErr)
       throw systemError(`Title updated but FTS refresh failed: ${ftsErr.message}`);
   }
-  const author = resolveAuthor(options.author);
-  const authorType = resolveAuthorType(options.authorType);
-  if (author === "unknown") {
-    warn("No --author / CEREFOX_AUTHOR_NAME set — audit log will record this write as 'unknown'.");
+  if (titleChanged) {
+    await client.raw.rpc("cerefox_create_audit_entry", {
+      p_document_id: documentId,
+      p_operation: "update-metadata",
+      p_author: author,
+      p_author_type: authorType,
+      p_description: "Edited title"
+    });
   }
-  await client.raw.rpc("cerefox_create_audit_entry", {
-    p_document_id: documentId,
-    p_operation: "update-metadata",
-    p_author: author,
-    p_author_type: authorType,
-    p_description: `Edited${titleChanged ? " title" : ""}` + (sets.length ? ` · set ${sets.length} meta key(s)` : "") + (unsets.length ? ` · unset ${unsets.length} meta key(s)` : "")
-  });
   println(c.green(`✓ Edited "${newTitle}" (id: ${documentId}).`));
   if (titleChanged) {
     println(c.dim("  Title changed: FTS refreshed; semantic embeddings update on next `cerefox server reindex`."));
@@ -73337,13 +73394,13 @@ function collect(value, prev) {
   return [...prev, value];
 }
 function registerDocumentEdit(parent) {
-  parent.command("edit").description("Edit a document's title and/or metadata (non-destructive patch). Content edits: `document ingest --document-id <id> --update`.").argument("<document-id>", "UUID of the document.").option("--title <title>", "New title (refreshes FTS; re-embed on next reindex).").option("--set-meta <key=value>", "Set/overwrite a metadata key (repeatable). Value is JSON-parsed when possible.", collect, []).option("--unset-meta <key>", "Remove a metadata key (repeatable).", collect, []).option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action10);
+  parent.command("edit").description("Edit a document's title and/or metadata (non-destructive patch). Content edits: `document ingest --document-id <id> --update`.").argument("<document-id>", "UUID of the document.").option("--title <title>", "New title (refreshes FTS; re-embed on next reindex).").option("--set-meta <key=value>", "Set/overwrite a metadata key (repeatable). Value is JSON-parsed when possible.", collect, []).option("--unset-meta <key>", "Remove a metadata key (repeatable).", collect, []).option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action11);
 }
 
 // src/cli/commands/document-restore.ts
 init_cli_core();
 init_client();
-async function action11(documentId, options) {
+async function action12(documentId, options) {
   const client = getClient();
   const { data: doc, error } = await client.raw.from("cerefox_documents").select("id, title, deleted_at").eq("id", documentId).maybeSingle();
   if (error)
@@ -73397,13 +73454,13 @@ async function action11(documentId, options) {
   }
 }
 function registerDocumentRestore(parent) {
-  parent.command("restore").description("Restore a soft-deleted document from the trash (inverse of `document delete`).").argument("<document-id>", "UUID of the soft-deleted document.").option("--reason <text>", "Optional reason recorded in the audit log.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action11);
+  parent.command("restore").description("Restore a soft-deleted document from the trash (inverse of `document delete`).").argument("<document-id>", "UUID of the soft-deleted document.").option("--reason <text>", "Optional reason recorded in the audit log.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action12);
 }
 
 // src/cli/commands/document-set-metadata.ts
 init_cli_core();
 init_client();
-async function action12(documentId, options) {
+async function action13(documentId, options) {
   const patch = {};
   if (options.json) {
     let parsed;
@@ -73475,14 +73532,14 @@ async function action12(documentId, options) {
   println(c.dim("  Content untouched — no new version, no re-embedding."));
 }
 function registerDocumentSetMetadata(parent) {
-  parent.command("set-metadata").description("Change a document's metadata without resending its content (merges by default).").argument("<document-id>", "UUID of the document.").option("-s, --set <key=value...>", "Set a key. Repeatable. Values are stored as JSON strings; quote to force JSON parsing.").option("-r, --remove <key...>", "Remove a key. Repeatable. (Sends a JSON null.)").option("--json <object>", "A JSON object of keys to set; a null value removes that key.").option("--replace", "Set the metadata to EXACTLY what was given, discarding every key not listed. Default is merge.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").option("--json-out", "Emit the result as JSON.").action(action12);
+  parent.command("set-metadata").description("Change a document's metadata without resending its content (merges by default).").argument("<document-id>", "UUID of the document.").option("-s, --set <key=value...>", "Set a key. Repeatable. Values are stored as JSON strings; quote to force JSON parsing.").option("-r, --remove <key...>", "Remove a key. Repeatable. (Sends a JSON null.)").option("--json <object>", "A JSON object of keys to set; a null value removes that key.").option("--replace", "Set the metadata to EXACTLY what was given, discarding every key not listed. Default is merge.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").option("--json-out", "Emit the result as JSON.").action(action13);
 }
 
 // src/cli/commands/document-set-projects.ts
 init_cli_core();
 init__projects();
 init_client();
-async function action13(documentId, projectNames, options) {
+async function action14(documentId, projectNames, options) {
   const names = projectNames ?? [];
   if (options.clear && names.length > 0) {
     throw userError("Pass either project names or --clear, not both.", "Use --clear on its own to remove the document from all projects.");
@@ -73512,7 +73569,7 @@ async function action13(documentId, projectNames, options) {
   println(c.dim("  This REPLACED the previous set — any project not listed is no longer associated."));
 }
 function registerDocumentSetProjects(parent) {
-  parent.command("set-projects").description("Replace a document's project memberships with exactly the given set (or --clear to remove all).").argument("<document-id>", "UUID of the document.").argument("[project-names...]", "Project names to set (created if missing). Omit and pass --clear to remove all.").option("--clear", "Remove the document from all projects.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action13);
+  parent.command("set-projects").description("Replace a document's project memberships with exactly the given set (or --clear to remove all).").argument("<document-id>", "UUID of the document.").argument("[project-names...]", "Project names to set (created if missing). Omit and pass --clear to remove all.").option("--clear", "Remove the document from all projects.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action14);
 }
 
 // src/cli/commands/guides.ts
@@ -73562,7 +73619,7 @@ function registerGuides(parent) {
 // src/cli/commands/project-create.ts
 init_cli_core();
 init_client();
-async function action14(name, options) {
+async function action15(name, options) {
   const trimmed = name.trim();
   if (!trimmed)
     throw userError("Project name is required.");
@@ -73574,14 +73631,14 @@ async function action14(name, options) {
   println(c.green(`✓ Created project "${data.name}" (id: ${data.id}).`));
 }
 function registerProjectCreate(parent) {
-  parent.command("create").description("Create a new (empty) project.").argument("<name>", "Project name (must be unique).").option("--description <text>", "Optional project description.").action(action14);
+  parent.command("create").description("Create a new (empty) project.").argument("<name>", "Project name (must be unique).").option("--description <text>", "Optional project description.").action(action15);
 }
 
 // src/cli/commands/project-edit.ts
 init_cli_core();
 init_client();
 var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-async function action15(target, options) {
+async function action16(target, options) {
   const update = {};
   if (options.name !== undefined) {
     const n = options.name.trim();
@@ -73608,7 +73665,7 @@ async function action15(target, options) {
   println(c.green(`✓ Updated project "${data.name}" (id: ${data.id}).`));
 }
 function registerProjectEdit(parent) {
-  parent.command("edit").description("Rename a project and/or change its description.").argument("<name-or-id>", "Project name (exact match) or UUID.").option("--name <new-name>", "New project name.").option("--description <text>", "New project description.").action(action15);
+  parent.command("edit").description("Rename a project and/or change its description.").argument("<name-or-id>", "Project name (exact match) or UUID.").option("--name <new-name>", "New project name.").option("--description <text>", "New project description.").action(action16);
 }
 
 // src/cli/commands/version-archive.ts
@@ -77430,14 +77487,9 @@ async function checkEmbedderMismatch() {
     };
   }
 }
-var CONTENT_FORMAT_CHECK_NAME = "content format";
-async function checkContentFormat() {
-  const settings = loadSettings();
-  if (!settings.supabaseUrl || !settings.supabaseKey) {
-    return { name: CONTENT_FORMAT_CHECK_NAME, status: "skipped", detail: "Supabase config missing; skipped." };
-  }
+async function probeRpcJson(settings, fn) {
   try {
-    const url = `${settings.supabaseUrl.replace(/\/$/, "")}/rest/v1/rpc/cerefox_content_format_stats`;
+    const url = `${settings.supabaseUrl.replace(/\/$/, "")}/rest/v1/rpc/${fn}`;
     const resp = await fetch(url, {
       method: "POST",
       headers: {
@@ -77447,14 +77499,38 @@ async function checkContentFormat() {
       },
       body: "{}"
     });
-    if (!resp.ok) {
+    if (resp.status === 404)
+      return { kind: "absent" };
+    if (!resp.ok)
+      return { kind: "error", detail: `HTTP ${resp.status}` };
+    return { kind: "ok", rows: await resp.json() };
+  } catch (err) {
+    return { kind: "error", detail: err instanceof Error ? err.message : String(err) };
+  }
+}
+var CONTENT_FORMAT_CHECK_NAME = "content format";
+async function checkContentFormat() {
+  const settings = loadSettings();
+  if (!settings.supabaseUrl || !settings.supabaseKey) {
+    return { name: CONTENT_FORMAT_CHECK_NAME, status: "skipped", detail: "Supabase config missing; skipped." };
+  }
+  {
+    const probe = await probeRpcJson(settings, "cerefox_content_format_stats");
+    if (probe.kind === "absent") {
       return {
         name: CONTENT_FORMAT_CHECK_NAME,
         status: "skipped",
-        detail: `format stats unavailable (${resp.status}); deploy schema 0.8.0 to enable.`
+        detail: "format stats unavailable; deploy schema 0.8.0 to enable."
       };
     }
-    const rows = await resp.json();
+    if (probe.kind === "error") {
+      return {
+        name: CONTENT_FORMAT_CHECK_NAME,
+        status: "skipped",
+        detail: `content-format check skipped (${probe.detail}).`
+      };
+    }
+    const rows = probe.rows;
     const legacy = rows[0]?.legacy_docs ?? 0;
     const total = rows[0]?.total_docs ?? 0;
     if (legacy === 0) {
@@ -77470,13 +77546,39 @@ async function checkContentFormat() {
       detail: `${legacy} of ${total} document(s) use the legacy reconstruction format (format 1).`,
       hint: "Harmless — they auto-convert on next edit. To convert them all now: `cerefox server migrate-format` (re-embeds, so try `--dry-run` first). To read what chunk formats are: `cerefox guides show content-format`."
     };
-  } catch (err) {
+  }
+}
+var METADATA_HEALTH_CHECK_NAME = "metadata health";
+async function checkMetadataHealth() {
+  const settings = loadSettings();
+  if (!settings.supabaseUrl || !settings.supabaseKey) {
+    return { name: METADATA_HEALTH_CHECK_NAME, status: "skipped", detail: "Supabase config missing; skipped." };
+  }
+  const probe = await probeRpcJson(settings, "cerefox_metadata_health");
+  if (probe.kind === "absent") {
     return {
-      name: CONTENT_FORMAT_CHECK_NAME,
+      name: METADATA_HEALTH_CHECK_NAME,
+      status: "skipped",
+      detail: "metadata-health RPC not deployed; deploy schema 0.12.2 to enable."
+    };
+  }
+  if (probe.kind === "error") {
+    return {
+      name: METADATA_HEALTH_CHECK_NAME,
       status: "skipped",
-      detail: `content-format check skipped: ${err instanceof Error ? err.message : String(err)}`
+      detail: `metadata-health check skipped (${probe.detail}).`
     };
   }
+  if (probe.rows.length === 0) {
+    return { name: METADATA_HEALTH_CHECK_NAME, status: "ok", detail: "all document metadata is well-formed" };
+  }
+  const sample = probe.rows.slice(0, 3).map((r) => `"${r.document_title}" (${r.metadata_type})`).join(", ");
+  return {
+    name: METADATA_HEALTH_CHECK_NAME,
+    status: "skipped",
+    detail: `${probe.rows.length} document(s) hold non-object metadata: ${sample}${probe.rows.length > 3 ? ", …" : ""}.`,
+    hint: "Writes that would merge onto these rows are refused (#212). Repair each with `cerefox document set-metadata <id> --replace --json '<the intended object>'`."
+  };
 }
 function hasCerefoxInJsonFile(path) {
   if (!existsSync10(path))
@@ -77687,6 +77789,7 @@ async function runAllChecks(opts = {}) {
     { name: "schema + RPCs", phase: "Reading schema + RPC version", run: () => checkSchemaVersion() },
     { name: "embedder", phase: "Checking embedder consistency", run: () => checkEmbedderMismatch() },
     { name: "content format", phase: "Checking chunk reconstruction format", run: () => checkContentFormat() },
+    { name: "metadata health", phase: "Checking metadata well-formedness", run: () => checkMetadataHealth() },
     { name: "edge functions", phase: "Probing Edge Function versions", run: () => checkEdgeFunctionsCompat() },
     { name: "postgres", phase: "Probing Postgres DDL endpoint", run: () => checkPostgres() },
     { name: "mcp clients", phase: "Scanning MCP client configs", run: () => checkMcpConfigs() }
@@ -77715,7 +77818,7 @@ function symbol(status) {
       return cErr.dim("ℹ");
   }
 }
-async function action16(options) {
+async function action17(options) {
   const useSpinner = !options.json && process.stderr.isTTY;
   const spinner = useSpinner ? ora({ text: "Starting checks…", spinner: "dots", stream: process.stderr }).start() : null;
   const results = await runAllChecks({
@@ -77779,13 +77882,13 @@ async function action16(options) {
     process.exit(1);
 }
 function registerDoctor(program2) {
-  program2.command("doctor").description("Run diagnostic checks against the installed Cerefox.").option("--json", "Emit machine-readable JSON (no colours, structured output).").option("--strict", "Exit non-zero when any check warns (default: only errors fail).").action(action16);
+  program2.command("doctor").description("Run diagnostic checks against the installed Cerefox.").option("--json", "Emit machine-readable JSON (no colours, structured output).").option("--strict", "Exit non-zero when any check warns (default: only errors fail).").action(action17);
 }
 
 // src/cli/commands/get-audit-log.ts
 init_cli_core();
 init_client();
-async function action17(options) {
+async function action18(options) {
   const limit = parsePositiveInt(options.limit, "--limit", 50);
   const client = getClient();
   const data = await client.rpc("cerefox_list_audit_entries", {
@@ -77823,7 +77926,7 @@ async function action17(options) {
   })));
 }
 function registerGetAuditLog(program2) {
-  program2.command("get-audit-log").description("Query the audit log with optional filters.").option("-d, --document-id <uuid>", "Filter by document.").option("-a, --author <name>", "Filter by author.").option("-o, --operation <type>", "Filter by operation: create, update-content, update-metadata, delete, restore.").option("--since <iso>", "Lower-bound ISO timestamp.").option("--until <iso>", "Upper-bound ISO timestamp.").option("-l, --limit <n>", "Maximum entries (max 200).", "50").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action17);
+  program2.command("get-audit-log").description("Query the audit log with optional filters.").option("-d, --document-id <uuid>", "Filter by document.").option("-a, --author <name>", "Filter by author.").option("-o, --operation <type>", "Filter by operation: create, update-content, update-metadata, delete, restore.").option("--since <iso>", "Lower-bound ISO timestamp.").option("--until <iso>", "Upper-bound ISO timestamp.").option("-l, --limit <n>", "Maximum entries (max 200).", "50").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action18);
 }
 
 // src/cli/commands/relation.ts
@@ -77959,7 +78062,7 @@ init_cli_core();
 init_cli_core();
 init_partial_edits();
 init_client();
-async function action18(documentId, options) {
+async function action19(documentId, options) {
   const section = (options.section ?? "").trim() || null;
   if (section && options.outline) {
     throw userError("Pass either --outline (the whole structure) or --section (one section's text), not both.");
@@ -78056,7 +78159,7 @@ async function action18(documentId, options) {
   println(doc.full_content);
 }
 function registerGetDoc(program2) {
-  program2.command("get-doc").description("Retrieve the full content of a document by ID.").argument("<document-id>", "UUID of the document.").option("--version-id <uuid>", "Specific archived version (default: current).").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").option("--outline", "Show the heading structure, per-section sizes and content_hash instead of the content. Cheap, and the paths are the anchors the edit commands take.").option("--section <anchor>", "Show ONE section's text instead of the whole document: exactly what a replace_section on this anchor would overwrite. Pass the bare heading line when it is unique, or the full ' > ' path from --outline when it repeats.").option("--section-part <part>", "own_body | subtree — only when the target section has child sections, where 'the end' means two different places. You are told (with both options) whenever it is needed.").action(action18);
+  program2.command("get-doc").description("Retrieve the full content of a document by ID.").argument("<document-id>", "UUID of the document.").option("--version-id <uuid>", "Specific archived version (default: current).").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").option("--outline", "Show the heading structure, per-section sizes and content_hash instead of the content. Cheap, and the paths are the anchors the edit commands take.").option("--section <anchor>", "Show ONE section's text instead of the whole document: exactly what a replace_section on this anchor would overwrite. Pass the bare heading line when it is unique, or the full ' > ' path from --outline when it repeats.").option("--section-part <part>", "own_body | subtree — only when the target section has child sections, where 'the end' means two different places. You are told (with both options) whenever it is needed.").action(action19);
 }
 
 // src/cli/commands/ingest.ts
@@ -78720,7 +78823,7 @@ async function readContent(path, paste) {
   const titleFromPath = basename2(path, extname3(path));
   return { content, titleFromPath };
 }
-async function action19(path, options) {
+async function action20(path, options) {
   const { content, titleFromPath } = await readContent(path, Boolean(options.paste));
   const updatingById = Boolean(options.documentId);
   let title = options.title ?? (updatingById ? null : titleFromPath);
@@ -78811,7 +78914,7 @@ async function action19(path, options) {
   }
 }
 function registerIngest(program2) {
-  program2.command("ingest").description("Ingest a file (or stdin paste) into the knowledge base.").argument("[path]", "Path to the file to ingest. Omit when using --paste.").option("--paste", "Read content from stdin instead of a file.").option("-t, --title <title>", "Document title (required with --paste; defaults to filename without extension).").option("-p, --project-name <name>", "Single project membership (non-destructive on update).").option("-P, --project-names <names>", "Comma-separated full project membership set (destructive replace on update).").option("-m, --metadata <json>", "JSON metadata object.").option("--source <label>", 'Origin label. Omit it on an update and the document keeps the source it already has (#193); omit it on a create and it is recorded as "cli".').option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-i, --document-id <uuid>", "Update a specific document by UUID (overrides --update-if-exists).").option("--expected-content-hash <sha256>", "Optimistic-concurrency token: the content_hash of the version this edit is based on (shown by `document get` / `search`). Required on content updates unless --last-write-wins.").option("--last-write-wins", "Skip the concurrency check and overwrite regardless of concurrent changes (recorded in the audit log).").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action19);
+  program2.command("ingest").description("Ingest a file (or stdin paste) into the knowledge base.").argument("[path]", "Path to the file to ingest. Omit when using --paste.").option("--paste", "Read content from stdin instead of a file.").option("-t, --title <title>", "Document title (required with --paste; defaults to filename without extension).").option("-p, --project-name <name>", "Single project membership (non-destructive on update).").option("-P, --project-names <names>", "Comma-separated full project membership set (destructive replace on update).").option("-m, --metadata <json>", "JSON metadata object.").option("--source <label>", 'Origin label. Omit it on an update and the document keeps the source it already has (#193); omit it on a create and it is recorded as "cli".').option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-i, --document-id <uuid>", "Update a specific document by UUID (overrides --update-if-exists).").option("--expected-content-hash <sha256>", "Optimistic-concurrency token: the content_hash of the version this edit is based on (shown by `document get` / `search`). Required on content updates unless --last-write-wins.").option("--last-write-wins", "Skip the concurrency check and overwrite regardless of concurrent changes (recorded in the audit log).").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").action(action20);
 }
 
 // src/cli/commands/document-partial-edit.ts
@@ -78914,7 +79017,7 @@ function walk(dir, extensions) {
   }
   return files;
 }
-async function action20(dir, options) {
+async function action21(dir, options) {
   const extensions = new Set((options.extensions ?? ".md,.txt").split(",").map((e) => e.trim().toLowerCase()).map((e) => e.startsWith(".") ? e : "." + e).filter((e) => e.length > 0));
   const files = walk(dir, extensions);
   if (files.length === 0) {
@@ -78989,7 +79092,7 @@ async function action20(dir, options) {
   }
 }
 function registerIngestDir(program2) {
-  program2.command("ingest-dir").description("Recursively ingest a directory of markdown / text files.").argument("<dir>", "Root directory to walk.").option("-p, --project-name <name>", "Project membership for all ingested docs.").option("-m, --metadata <json>", "JSON metadata applied to every doc.").option("--source <label>", 'Origin label. Omit it and each matched document keeps the source it already has (#193); newly created ones are recorded as "cli".').option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").option("-e, --extensions <list>", "Comma-separated file extensions to ingest.", ".md,.txt").action(action20);
+  program2.command("ingest-dir").description("Recursively ingest a directory of markdown / text files.").argument("<dir>", "Root directory to walk.").option("-p, --project-name <name>", "Project membership for all ingested docs.").option("-m, --metadata <json>", "JSON metadata applied to every doc.").option("--source <label>", 'Origin label. Omit it and each matched document keeps the source it already has (#193); newly created ones are recorded as "cli".').option("-u, --update-if-exists", "Update an existing doc with the same title.").option("-a, --author <name>", "Caller identity (audit log).").option("--author-type <type>", "'user' or 'agent' (default: user).", "user").option("-e, --extensions <list>", "Comma-separated file extensions to ingest.", ".md,.txt").action(action21);
 }
 
 // src/cli/commands/init.ts
@@ -79320,7 +79423,7 @@ function writeAnswersTo(target, answers) {
     }
   }
 }
-async function action22(options) {
+async function action23(options) {
   const homeEnv = join11(homedir7(), USER_STATE_DIR_NAME, ".env");
   const cwdEnv = join11(process.cwd(), ".env");
   const explicitDir = (process.env.CEREFOX_CONFIG_DIR ?? "").trim();
@@ -79429,13 +79532,13 @@ async function action22(options) {
   await postWriteLifecycle(target, options);
 }
 function registerInit(program2) {
-  program2.command("init").description("Interactive first-run setup (config, schema deploy stub, optional MCP wiring).").option("-c, --config <file>", "Non-interactive mode: read answers from a JSON file.").option("--force", "Overwrite existing configuration without prompting.").option("--skip-schema", "Skip the schema deploy step.").option("--skip-self-docs", "Skip the bundled self-doc ingest.").option("--skip-agent-config", "Skip the optional MCP agent wiring.").action(action22);
+  program2.command("init").description("Interactive first-run setup (config, schema deploy stub, optional MCP wiring).").option("-c, --config <file>", "Non-interactive mode: read answers from a JSON file.").option("--force", "Overwrite existing configuration without prompting.").option("--skip-schema", "Skip the schema deploy step.").option("--skip-self-docs", "Skip the bundled self-doc ingest.").option("--skip-agent-config", "Skip the optional MCP agent wiring.").action(action23);
 }
 
 // src/cli/commands/list-docs.ts
 init_cli_core();
 init_client();
-async function action23(options) {
+async function action24(options) {
   const deleted = !!options.deleted;
   const limit = parsePositiveInt(options.limit, "--limit", 100);
   const client = getClient();
@@ -79491,13 +79594,13 @@ async function action23(options) {
   }));
 }
 function registerListDocs(program2) {
-  program2.command("list-docs").description("List documents in the knowledge base.").option("-p, --project <name>", "Filter to a specific project.").option("-l, --limit <n>", "Maximum docs to return.", "100").option("--deleted", "List soft-deleted (trashed) documents instead of active ones.").option("--json", "Emit machine-readable JSON.").action(action23);
+  program2.command("list-docs").description("List documents in the knowledge base.").option("-p, --project <name>", "Filter to a specific project.").option("-l, --limit <n>", "Maximum docs to return.", "100").option("--deleted", "List soft-deleted (trashed) documents instead of active ones.").option("--json", "Emit machine-readable JSON.").action(action24);
 }
 
 // src/cli/commands/list-metadata-keys.ts
 init_cli_core();
 init_client();
-async function action24(options) {
+async function action25(options) {
   const client = getClient();
   const data = await client.rpc("cerefox_list_metadata_keys");
   if (data === null) {
@@ -79525,13 +79628,13 @@ async function action24(options) {
   })));
 }
 function registerListMetadataKeys(program2) {
-  program2.command("list-metadata-keys").description("List all metadata keys with document counts and example values.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action24);
+  program2.command("list-metadata-keys").description("List all metadata keys with document counts and example values.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action25);
 }
 
 // src/cli/commands/list-projects.ts
 init_cli_core();
 init_client();
-async function action25(options) {
+async function action26(options) {
   const client = getClient();
   const { data, error: error2 } = await client.raw.from("cerefox_projects").select("id, name, description, created_at").order("name", { ascending: true });
   if (error2) {
@@ -79560,13 +79663,13 @@ async function action25(options) {
   })), "(no projects)");
 }
 function registerListProjects(program2) {
-  program2.command("list-projects").description("List all projects in the knowledge base.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action25);
+  program2.command("list-projects").description("List all projects in the knowledge base.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action26);
 }
 
 // src/cli/commands/list-versions.ts
 init_cli_core();
 init_client();
-async function action26(documentId, options) {
+async function action27(documentId, options) {
   const client = getClient();
   const data = await client.rpc("cerefox_list_document_versions", {
     p_document_id: documentId
@@ -79607,7 +79710,7 @@ async function action26(documentId, options) {
   })));
 }
 function registerListVersions(program2) {
-  program2.command("list-versions").description("List archived versions of a document.").argument("<document-id>", "UUID of the document.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action26);
+  program2.command("list-versions").description("List archived versions of a document.").argument("<document-id>", "UUID of the document.").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action27);
 }
 
 // src/cli/commands/mcp.ts
@@ -79639,7 +79742,7 @@ function registerEmbedderWarmup(program2) {
 // src/cli/commands/metadata-search.ts
 init_cli_core();
 init_client();
-async function action27(options) {
+async function action28(options) {
   const metadataFilter = parseJsonObjectArg(options.metadataFilter, "--metadata-filter") ?? {};
   if (Object.keys(metadataFilter).length === 0 && !options.projectName && !options.updatedSince && !options.createdSince) {
     throw userError("Provide at least one of: --metadata-filter, --project-name, --updated-since, or --created-since.", `Examples: --metadata-filter '{"type":"decision-log"}' · --project-name "research" (lists that project's docs).`);
@@ -79702,7 +79805,7 @@ async function action27(options) {
   }
 }
 function registerMetadataSearch(program2) {
-  program2.command("metadata-search").description("Find or list documents by metadata, project, or time criteria (no text query).").option("-f, --metadata-filter <json>", "JSON object; only docs whose metadata contains ALL pairs are returned. Optional — omit to list by --project-name / time range alone (at least one criterion is required).").option("-p, --project-name <name>", "Filter to a specific project.").option("--updated-since <iso>", "Only docs updated on/after this ISO timestamp.").option("--created-since <iso>", "Only docs created on/after this ISO timestamp.").option("--include-content", "Include full document text in results.").option("-l, --limit <n>", "Maximum docs to return.", "10").option("--max-bytes <n>", "Response size budget in bytes (with --include-content).", "200000").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action27);
+  program2.command("metadata-search").description("Find or list documents by metadata, project, or time criteria (no text query).").option("-f, --metadata-filter <json>", "JSON object; only docs whose metadata contains ALL pairs are returned. Optional — omit to list by --project-name / time range alone (at least one criterion is required).").option("-p, --project-name <name>", "Filter to a specific project.").option("--updated-since <iso>", "Only docs updated on/after this ISO timestamp.").option("--created-since <iso>", "Only docs created on/after this ISO timestamp.").option("--include-content", "Include full document text in results.").option("-l, --limit <n>", "Maximum docs to return.", "10").option("--max-bytes <n>", "Response size budget in bytes (with --include-content).", "200000").option("-r, --requestor <name>", "Agent / user name (usage log).").option("--json", "Emit machine-readable JSON.").action(action28);
 }
 
 // src/cli/commands/reindex.ts
@@ -79728,7 +79831,7 @@ function warnLargeBulkWrite(opts) {
 }
 
 // src/cli/commands/reindex.ts
-async function action28(options) {
+async function action29(options) {
   const settings = loadSettings();
   if (!settings.supabaseUrl || !settings.supabaseKey) {
     throw userError("Supabase credentials not configured — run `cerefox init` first.");
@@ -79818,7 +79921,7 @@ ${c2.content}`;
   }
 }
 function registerReindex(program2) {
-  program2.command("reindex").description("Re-embed existing document chunks (v0.7+).").option("--all", "Reindex every chunk regardless of embedder.").option("--batch <n>", "Chunks per OpenAI batch call. Capped at 96 internally.", "32").option("--dry-run", "Show counts without re-embedding.").option("-i, --document-id <uuid>", "Limit reindex to a single document.").action(action28);
+  program2.command("reindex").description("Re-embed existing document chunks (v0.7+).").option("--all", "Reindex every chunk regardless of embedder.").option("--batch <n>", "Chunks per OpenAI batch call. Capped at 96 internally.", "32").option("--dry-run", "Show counts without re-embedding.").option("-i, --document-id <uuid>", "Limit reindex to a single document.").action(action29);
 }
 
 // src/cli/commands/migrate-format.ts
@@ -79826,7 +79929,7 @@ init_cli_core();
 init_config();
 init_client();
 var CURRENT_FORMAT = 2;
-async function action29(options) {
+async function action30(options) {
   const settings = loadSettings();
   const client = getClient();
   const supabase = client.raw;
@@ -79953,7 +80056,7 @@ async function action29(options) {
   }
 }
 function registerMigrateFormat(program2) {
-  program2.command("migrate-format").description("Convert legacy-format documents to the current chunk format (re-chunks + re-embeds).").option("--dry-run", "Report how many documents would be converted; write nothing.").option("-l, --limit <n>", "Convert at most N documents (re-run to continue).").option("--document-id <uuid>", "Convert a single document.").option("--author <name>", "Recorded in the audit log for each conversion.").action(action29);
+  program2.command("migrate-format").description("Convert legacy-format documents to the current chunk format (re-chunks + re-embeds).").option("--dry-run", "Report how many documents would be converted; write nothing.").option("-l, --limit <n>", "Convert at most N documents (re-run to continue).").option("--document-id <uuid>", "Convert a single document.").option("--author <name>", "Recorded in the audit log for each conversion.").action(action30);
 }
 
 // src/cli/commands/restore.ts
@@ -79983,7 +80086,7 @@ function resolveBackupFile(target) {
   }
   return join12(path, candidates[0].name);
 }
-async function action30(target, options) {
+async function action31(target, options) {
   const file = resolveBackupFile(target);
   let payload;
   try {
@@ -80118,7 +80221,7 @@ async function action30(target, options) {
   }
 }
 function registerRestore(program2) {
-  program2.command("restore").description("Restore a JSON-snapshot backup into the knowledge base.").argument("<snapshot>", "Backup file (or directory; most recent is picked) produced by `cerefox backup`.").option("--dry-run", "Print what would be restored without writing.").option("-p, --project-name <name>", "Reserved for future use; currently ignored. Project memberships are restored from the backup itself (format 2+).").action(action30);
+  program2.command("restore").description("Restore a JSON-snapshot backup into the knowledge base.").argument("<snapshot>", "Backup file (or directory; most recent is picked) produced by `cerefox backup`.").option("--dry-run", "Print what would be restored without writing.").option("-p, --project-name <name>", "Reserved for future use; currently ignored. Project memberships are restored from the backup itself (format 2+).").action(action31);
 }
 
 // src/cli/commands/search.ts
@@ -80143,7 +80246,7 @@ async function embedQuery(query) {
 }
 
 // src/cli/commands/search.ts
-async function action31(query, options) {
+async function action32(query, options) {
   if (!query || query.trim() === "") {
     throw userError("Empty query.");
   }
@@ -80309,7 +80412,7 @@ async function action31(query, options) {
   }
 }
 function registerSearch(program2) {
-  program2.command("search").description("Search the knowledge base (hybrid FTS + semantic).").argument("<query>", "Natural-language search query.").option("-c, --match-count <n>", "Maximum number of documents to return.", "5").option("-p, --project-name <name>", "Filter results to a specific project.").option("-f, --metadata-filter <json>", "JSON containment filter; only docs whose metadata contains ALL pairs are returned.").option("--mode <mode>", "Search mode: docs (default), hybrid, fts.", "docs").option("--alpha <float>", "Semantic weight 0..1 (default: CEREFOX_SEARCH_ALPHA; else 0.7).").option("--min-score <float>", "Minimum cosine similarity threshold (default: CEREFOX_MIN_SEARCH_SCORE; else 0.5, or 0.6 with the local embedder).").option("--min-term-coverage <float>", "OR-fallback keyword matches must cover at least this fraction of the query's meaningful terms to count as confident hits (default: CEREFOX_MIN_TERM_COVERAGE; else the server default 0.5; needs schema ≥ 0.9.1).").option("--max-bytes <n>", "Response size budget in bytes (default: CEREFOX_MAX_RESPONSE_BYTES or 200000).").option("-r, --requestor <name>", "Agent / user name (recorded in usage log).").option("--json", "Emit machine-readable JSON instead of the default text.").option("--only-metadata", "List matching docs (id, score, chunks, chars, partial/full) WITHOUT their content — like the web UI's collapsed result list. Grab a [id:…] then `cerefox document get <id>`.").action(action31);
+  program2.command("search").description("Search the knowledge base (hybrid FTS + semantic).").argument("<query>", "Natural-language search query.").option("-c, --match-count <n>", "Maximum number of documents to return.", "5").option("-p, --project-name <name>", "Filter results to a specific project.").option("-f, --metadata-filter <json>", "JSON containment filter; only docs whose metadata contains ALL pairs are returned.").option("--mode <mode>", "Search mode: docs (default), hybrid, fts.", "docs").option("--alpha <float>", "Semantic weight 0..1 (default: CEREFOX_SEARCH_ALPHA; else 0.7).").option("--min-score <float>", "Minimum cosine similarity threshold (default: CEREFOX_MIN_SEARCH_SCORE; else 0.5, or 0.6 with the local embedder).").option("--min-term-coverage <float>", "OR-fallback keyword matches must cover at least this fraction of the query's meaningful terms to count as confident hits (default: CEREFOX_MIN_TERM_COVERAGE; else the server default 0.5; needs schema ≥ 0.9.1).").option("--max-bytes <n>", "Response size budget in bytes (default: CEREFOX_MAX_RESPONSE_BYTES or 200000).").option("-r, --requestor <name>", "Agent / user name (recorded in usage log).").option("--json", "Emit machine-readable JSON instead of the default text.").option("--only-metadata", "List matching docs (id, score, chunks, chars, partial/full) WITHOUT their content — like the web UI's collapsed result list. Grab a [id:…] then `cerefox document get <id>`.").action(action32);
 }
 
 // src/cli/commands/self-update.ts
@@ -80356,7 +80459,7 @@ async function fetchLatestVersion() {
   }
   return body.version;
 }
-async function action32(options) {
+async function action33(options) {
   let target;
   try {
     target = options.version ?? await fetchLatestVersion();
@@ -80409,7 +80512,7 @@ async function action32(options) {
 }
 function registerSelfUpdate(program2) {
   const desc = "Upgrade Cerefox in place. Alias: `cerefox upgrade`.";
-  const declaration = (cmd) => cmd.description(desc).option("--check", "Print current vs latest; do nothing.").option("--yes", "Non-interactive (skip confirmation).").option("--version <version>", "Pin a specific version (e.g. 0.5.1 or 0.6.0-rc.1).").action(action32);
+  const declaration = (cmd) => cmd.description(desc).option("--check", "Print current vs latest; do nothing.").option("--yes", "Non-interactive (skip confirmation).").option("--version <version>", "Pin a specific version (e.g. 0.5.1 or 0.6.0-rc.1).").action(action33);
   declaration(program2.command("self-update"));
   declaration(program2.command("upgrade"));
 }
@@ -80428,7 +80531,7 @@ function symbol2(status) {
       return cErr.dim("ℹ");
   }
 }
-async function action33(options) {
+async function action34(options) {
   const useSpinner = !options.json && process.stderr.isTTY;
   const spinner = useSpinner ? ora({ text: "Starting checks…", spinner: "dots", stream: process.stderr }).start() : null;
   const results = await runFastChecks({
@@ -80449,7 +80552,7 @@ async function action33(options) {
   }
 }
 function registerStatus(program2) {
-  program2.command("status").description("Quick sanity check (fast subset of `cerefox doctor`).").option("--json", "Emit machine-readable JSON.").action(action33);
+  program2.command("status").description("Quick sanity check (fast subset of `cerefox doctor`).").option("--json", "Emit machine-readable JSON.").action(action34);
 }
 
 // src/cli/commands/token.ts
@@ -80482,10 +80585,10 @@ function upsertEnvVar(path, key, value, opts = {}) {
   }
   const re = new RegExp(`^(\\s*)${escapeRegExp(key)}=.*$`, "m");
   let next;
-  let action34;
+  let action35;
   if (re.test(original)) {
     next = original.replace(re, `$1${line}`);
-    action34 = "updated";
+    action35 = "updated";
   } else {
     const base = original.endsWith(`
 `) ? original : `${original}
@@ -80493,10 +80596,10 @@ function upsertEnvVar(path, key, value, opts = {}) {
     next = `${base}
 ${header}${line}
 `;
-    action34 = "added";
+    action35 = "added";
   }
   writeFileSync5(path, next);
-  return { path, action: action34, backupPath };
+  return { path, action: action35, backupPath };
 }
 function readEnvVar(path, key) {
   if (!existsSync14(path))
@@ -85069,6 +85172,9 @@ function registerDocumentWriteRoutes(app, ctx) {
     const title = String(body.title ?? "").trim();
     const content = String(body.content ?? "");
     const projectIds = Array.isArray(body.project_ids) ? body.project_ids : [];
+    if (body.metadata !== undefined && body.metadata !== null && (typeof body.metadata !== "object" || Array.isArray(body.metadata))) {
+      return c2.json({ success: false, error: "metadata must be a JSON object of key/value pairs" }, 400);
+    }
     const metadata = body.metadata ?? {};
     const doc2 = await getCurrentDoc(ctx, documentId);
     if (!doc2) {
@@ -86334,6 +86440,7 @@ Learn more:
   moveInto(document2, registerGetDoc, "get");
   moveInto(document2, registerListDocs, "list");
   moveInto(document2, registerDeleteDoc, "delete");
+  moveInto(document2, registerDocumentDeadLinks, "dead-links");
   registerDocumentRestore(document2);
   registerDocumentEdit(document2);
   registerDocumentSetProjects(document2);

package/dist/server-assets/_shared/ef-meta/index.ts

@@ -18,7 +18,7 @@
  * doesn't touch `supabase/functions/` leaves it alone).
  */
 
-export const EF_VERSION = "1.7.0";
+export const EF_VERSION = "1.7.1";
 
 /**
  * The Cerefox RELEASE version — what `cerefox --version` reports and what npm
@@ -36,7 +36,7 @@ export const EF_VERSION = "1.7.0";
  * is imported by the Deno Edge Functions, which cannot reach into the npm
  * package.
  */
-export const CEREFOX_VERSION = "1.7.0";
+export const CEREFOX_VERSION = "1.7.1";
 
 /**
  * The most recent version whose EF-side SOURCE actually changed (#127).

package/dist/server-assets/db/migrations/0025_drop_orphaned_overloads.sql

@@ -0,0 +1,15 @@
+-- 0025_drop_orphaned_overloads.sql — remove pre-author-era 1-arg overloads.
+--
+-- cerefox_purge_document(UUID) and cerefox_restore_document(UUID) survived
+-- every CREATE OR REPLACE since their signatures grew (OR REPLACE only
+-- replaces the SAME signature), leaving long-lived databases with BOTH
+-- overloads. A named 1-arg call is then ambiguous — PostgREST PGRST203
+-- ("could not choose the best candidate") — which is how the first
+-- production acceptance run failed to purge its fixtures (v1.7.0).
+-- Fresh databases never had the old signatures and are unaffected.
+--
+-- Schema version 0.12.0 → 0.12.1. The DROPs also run from rpcs.sql on every
+-- deploy; this migration makes the version advance signal the redeploy.
+
+DROP FUNCTION IF EXISTS cerefox_purge_document(UUID);
+DROP FUNCTION IF EXISTS cerefox_restore_document(UUID);

package/dist/server-assets/db/migrations/0026_metadata_guard_and_dead_links.sql

@@ -0,0 +1,46 @@
+-- 0026_metadata_guard_and_dead_links.sql — #212 metadata type guards +
+-- #214 phase-2 dead-link sweep.
+--
+-- RPC changes ship via rpcs.sql on this deploy: cerefox_ingest_document
+-- rejects non-object p_metadata (the MCP layer always did; now every write
+-- path agrees), cerefox_set_document_metadata refuses to MERGE onto a
+-- non-object stored value (|| would produce an array; only replace=true
+-- repairs), and two read-only RPCs arrive: cerefox_find_dead_links (whole-KB
+-- [Text](uuid) sweep) and cerefox_metadata_health (rows with non-object
+-- metadata, surfaced by doctor).
+--
+-- Schema version 0.12.1 → 0.12.2. This migration also REPORTS (not repairs)
+-- any rows already in the non-object state, so the operator sees them at
+-- upgrade time; repair is `cerefox document set-metadata <id> --replace`.
+
+-- Table-level backstop (round-5 review): closes every current and future
+-- direct writer at once, not only the RPC/CLI/web paths patched in code.
+-- NOT VALID: legacy non-object rows survive (reported below) until repaired
+-- with `document set-metadata --replace`, which the constraint then checks.
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+        WHERE conname = 'cerefox_documents_metadata_object'
+    ) THEN
+        ALTER TABLE cerefox_documents
+            ADD CONSTRAINT cerefox_documents_metadata_object
+            CHECK (jsonb_typeof(metadata) = 'object') NOT VALID;
+    END IF;
+END $$;
+
+DO $$
+DECLARE
+    v_count INT;
+BEGIN
+    SELECT count(*) INTO v_count
+    FROM cerefox_documents
+    WHERE metadata IS NOT NULL AND jsonb_typeof(metadata) <> 'object';
+    IF v_count > 0 THEN
+        RAISE NOTICE
+            'Migration 0026: % document(s) hold NON-OBJECT metadata (legacy #212 state). List them with cerefox doctor (or SELECT * FROM cerefox_metadata_health()); repair each with cerefox document set-metadata <id> --replace --json ''<object>''.',
+            v_count;
+    ELSE
+        RAISE NOTICE 'Migration 0026: metadata guards + dead-link sweep arrive with rpcs.sql. No non-object metadata rows found. Schema 0.12.2.';
+    END IF;
+END $$;

package/dist/server-assets/db/rpcs.sql

@@ -1247,6 +1247,9 @@ $$;
 
 DROP FUNCTION IF EXISTS cerefox_restore_document(UUID, TEXT, TEXT, TEXT);
 DROP FUNCTION IF EXISTS cerefox_restore_document(UUID, TEXT, TEXT);
+-- 0.12.1: the pre-author 1-arg overload survived every CREATE OR REPLACE
+-- since the signature grew (same orphan class as purge; found live on prod).
+DROP FUNCTION IF EXISTS cerefox_restore_document(UUID);
 CREATE FUNCTION cerefox_restore_document(
     p_document_id   UUID,
     p_author        TEXT    DEFAULT 'unknown',
@@ -1309,7 +1312,14 @@ $$;
 -- ── cerefox_purge_document ───────────────────────────────────────────────────
 -- Permanently deletes a soft-deleted document (CASCADE). Only works on
 -- documents that are already soft-deleted (deleted_at IS NOT NULL).
+--
+-- 0.12.1: drop the pre-author 1-arg overload. CREATE OR REPLACE never removed
+-- it when the signature grew, so long-lived databases carried BOTH — and a
+-- 1-arg named call was ambiguous there (PGRST203), which is how the first
+-- prod acceptance run failed to purge its fixtures. Same cleanup for
+-- cerefox_restore_document below.
 
+DROP FUNCTION IF EXISTS cerefox_purge_document(UUID);
 CREATE OR REPLACE FUNCTION cerefox_purge_document(
     p_document_id   UUID,
     p_author        TEXT    DEFAULT 'unknown',
@@ -1347,6 +1357,43 @@ END;
 $$;
 
 
+-- ── cerefox_extract_doc_link_ids ─────────────────────────────────────────────
+-- The ONE implementation of [Text](uuid) link scanning (#214), shared by the
+-- write-time guard in cerefox_ingest_document and the cerefox_find_dead_links
+-- sweep — "same scanning rules" is enforced by this being the only copy.
+--
+-- Fences are LINE-ANCHORED and handled by SPLITTING, not by a paired-fence
+-- regex: Postgres AREs give the whole RE the greediness of their first
+-- quantified atom, which silently overrode a later .*? and made a closed
+-- fence strip everything to end-of-string (round-5 review, verified live) —
+-- blinding the scan to every link after any code block. Odd-numbered split
+-- segments are outside fences; an unterminated fence leaves its tail inside
+-- an even segment, dropped (under-validate, never false-reject). Inline code
+-- spans are stripped after (their regex has no greediness hazard).
+
+CREATE OR REPLACE FUNCTION cerefox_extract_doc_link_ids(p_content TEXT)
+RETURNS TABLE (link_id TEXT)
+LANGUAGE sql
+IMMUTABLE
+SET search_path = public, pg_catalog
+AS $$
+    WITH segments AS (
+        SELECT seg, row_number() OVER () AS rn
+        FROM regexp_split_to_table(COALESCE(p_content, ''), '^[ \t]*```.*$', 'n') AS seg
+    ),
+    outside AS (
+        SELECT string_agg(regexp_replace(seg, '`[^`]*`', ' ', 'g'), ' ') AS s
+        FROM segments
+        WHERE rn % 2 = 1
+    )
+    SELECT lower(m[1])
+    FROM outside,
+    LATERAL regexp_matches(
+        outside.s,
+        '\]\(([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\)',
+        'g') AS m;
+$$;
+
 -- ── cerefox_ingest_document ──────────────────────────────────────────────────
 -- Single RPC for ingesting a document (create or update). Handles:
 --   - Create: insert document row, insert chunks, set review_status, create audit entry
@@ -1494,6 +1541,19 @@ BEGIN
             USING ERRCODE = '22023';  -- invalid_parameter_value
     END IF;
 
+    -- ── Metadata type guard (#212, 0.12.2) ───────────────────────────────
+    -- metadata is jsonb and accepts ANY JSON value, but every reader assumes
+    -- an object — and `document edit`'s JS spread DECOMPOSED a stored string
+    -- into per-character keys (13 real documents were in the vulnerable
+    -- state). The MCP layer always validated this; the RPC now does too, so
+    -- every write path agrees (CLI, scripts, direct PostgREST included).
+    IF p_metadata IS NOT NULL AND jsonb_typeof(p_metadata) <> 'object' THEN
+        RAISE EXCEPTION
+            'cerefox_ingest_document: metadata must be a JSON object, got %. Wrap scalar values in a key ({"value": ...}).',
+            jsonb_typeof(p_metadata)
+            USING ERRCODE = '22023';  -- invalid_parameter_value
+    END IF;
+
     -- ── Link integrity (#214, 0.12.0) ────────────────────────────────────
     -- Validate [Text](uuid) document links against the store: agents mangle
     -- long random ids when regenerating text, and a mangled id silently
@@ -1506,23 +1566,14 @@ BEGIN
     -- See docs/specs/link-integrity-design.md.
     SELECT string_agg(c->>'content', E'\n') INTO v_scannable
     FROM jsonb_array_elements(p_chunks) c;
-    -- Fences are LINE-ANCHORED, matching markdown semantics: only ``` at a
-    -- line start opens/closes a block, so a stray backtick run mid-prose
-    -- cannot mis-pair the fences and un-escape a later real code block. An
-    -- unterminated fence strips to end-of-content (under-validates, never
-    -- false-rejects). Inline code is stripped after, so fence markers are
-    -- intact when pairing runs.
-    v_scannable := regexp_replace(
-        COALESCE(v_scannable, ''),
-        E'(^|\\n)[ \\t]*```.*?(\\n[ \\t]*```[^\\n]*|$)', ' ', 'g');
-    v_scannable := regexp_replace(v_scannable, '`[^`]*`', ' ', 'g');
-
-    SELECT array_agg(DISTINCT m[1]) INTO v_missing
-    FROM regexp_matches(
-        v_scannable,
-        '\]\(([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\)',
-        'g') m
-    WHERE NOT EXISTS (SELECT 1 FROM cerefox_documents d WHERE d.id = m[1]::uuid);
+
+    -- Scanning delegated to cerefox_extract_doc_link_ids — the one copy of
+    -- the fence/inline-code/uuid rules, shared with the dead-link sweep
+    -- (0.12.2; the previous inline regex was defeated by ARE whole-RE
+    -- greediness — see the helper's header).
+    SELECT array_agg(DISTINCT l.link_id) INTO v_missing
+    FROM cerefox_extract_doc_link_ids(v_scannable) l
+    WHERE NOT EXISTS (SELECT 1 FROM cerefox_documents d WHERE d.id = l.link_id::uuid);
 
     -- On UPDATE, tolerate dead links the document ALREADY carries: a target
     -- purged after linking must not make the document unwritable — sync
@@ -2662,6 +2713,30 @@ BEGIN
             USING ERRCODE = 'P0002';
     END IF;
 
+    -- #212: a legacy row can hold NON-OBJECT metadata (the ingest RPC did not
+    -- validate its input until 0.12.2). Merging onto it with || would produce
+    -- an ARRAY — Postgres treats both sides as arrays — burying the stored
+    -- value one level deeper and leaving the row still corrupt. Only replace
+    -- actually repairs such a row, so refuse the merge and say so. jsonb
+    -- 'null' is treated like SQL NULL (empty), matching the CLI.
+    IF NOT p_replace AND v_before IS NOT NULL
+       AND jsonb_typeof(v_before) NOT IN ('object', 'null') THEN
+        RAISE EXCEPTION
+            'CEREFOX_BAD_METADATA: stored metadata on document % is not an object (%). A merge cannot repair it — retry with replace (CLI: --replace; MCP: replace: true), passing the full intended object.',
+            p_document_id, jsonb_typeof(v_before)
+            USING ERRCODE = '22023';
+    END IF;
+
+    -- Normalized BEFORE value for merge and reporting: everything below must
+    -- work when the stored value is a scalar/array/'null' and p_replace is
+    -- true — that is the REPAIR path, and jsonb_object_keys on a scalar
+    -- errors, which would roll back the repair itself (round-5 review,
+    -- verified live).
+    v_before := CASE
+        WHEN v_before IS NULL OR jsonb_typeof(v_before) <> 'object' THEN '{}'::jsonb
+        ELSE v_before
+    END;
+
     -- Keys explicitly set to null are removals, never stored values.
     SELECT COALESCE(array_agg(key), ARRAY[]::TEXT[]) INTO v_null_keys
     FROM jsonb_each(p_metadata)
@@ -2713,6 +2788,11 @@ SET search_path = public, pg_catalog
 AS $$
     -- Keep in lockstep with the `@version:` marker in schema.sql (cut_release.ts
     -- enforces it). Bump whenever schema.sql OR rpcs.sql changes.
+    -- 0.12.2 (#212, #214): metadata must be a JSON object (ingest input guard
+    -- + set_document_metadata stored-state merge guard); cerefox_find_dead_links
+    -- (link-integrity phase-2 sweep); cerefox_metadata_health (doctor check).
+    -- 0.12.1: drop orphaned 1-arg overloads of purge/restore (pre-author era;
+    -- CREATE OR REPLACE never removed them; ambiguous PGRST203 on 1-arg calls).
     -- 0.12.0 (#208, #210): cerefox_delete_document — CAS
     -- (p_expected_content_hash), p_reason in audit description, JSONB return,
     -- idempotent re-delete; cerefox_restore_document — same rework (JSONB,
@@ -2726,7 +2806,75 @@ AS $$
     -- 0.11.0 supersedes 0.10.6 (v1.2.1, #191): this branch carries that fix plus
     -- the partial-edit surface, and both migrations (0019, 0020) are in the
     -- sequence, so a store deploying this gets everything from both lines.
-    SELECT '0.12.0'::TEXT;
+    SELECT '0.12.2'::TEXT;
+$$;
+
+-- ── cerefox_find_dead_links ──────────────────────────────────────────────────
+-- Phase 2 of link integrity (#214): a read-only whole-KB sweep for
+-- [Text](uuid) links whose target document no longer EXISTS (purged after
+-- linking). Complements the write-time guard, which validates only
+-- newly-introduced links on updates. Same scanning rules as the guard:
+-- line-anchored fences and inline code spans are stripped (examples are not
+-- links); a trashed target still exists and is NOT a dead link.
+-- Full chunk scan — run on demand (CLI `cerefox document dead-links`), not on
+-- every doctor.
+
+CREATE OR REPLACE FUNCTION cerefox_find_dead_links()
+RETURNS TABLE (
+    document_id     UUID,
+    document_title  TEXT,
+    dead_link_id    UUID,
+    occurrences     BIGINT
+)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+    -- Scanning delegated to cerefox_extract_doc_link_ids — the one copy of
+    -- the fence/inline-code/uuid rules, shared with the write-time guard.
+    -- Deliberate scope: trashed LINKER documents are excluded (they are
+    -- inert until restored; restoring one re-enters it into the next sweep).
+    WITH doc_content AS (
+        SELECT d.id, d.title, string_agg(c.content, E'\n' ORDER BY c.chunk_index) AS content
+        FROM cerefox_documents d
+        JOIN cerefox_chunks c ON c.document_id = d.id AND c.version_id IS NULL
+        WHERE d.deleted_at IS NULL
+        GROUP BY d.id, d.title
+    ),
+    links AS (
+        SELECT dc.id, dc.title, l.link_id AS target
+        FROM doc_content dc,
+        LATERAL cerefox_extract_doc_link_ids(dc.content) l
+    )
+    SELECT l.id, l.title, l.target::uuid, count(*)
+    FROM links l
+    WHERE NOT EXISTS (SELECT 1 FROM cerefox_documents t WHERE t.id = l.target::uuid)
+    GROUP BY l.id, l.title, l.target
+    ORDER BY l.title, l.target;
+$$;
+
+-- ── cerefox_metadata_health ──────────────────────────────────────────────────
+-- #212: rows whose stored metadata is not a JSON object — the state the
+-- 0.12.2 write guards now prevent, but which legacy rows may still be in.
+-- Cheap (documents table only); surfaced by `cerefox doctor`. Repair:
+-- `cerefox document set-metadata <id> --replace --json '<object>'`.
+
+CREATE OR REPLACE FUNCTION cerefox_metadata_health()
+RETURNS TABLE (
+    document_id     UUID,
+    document_title  TEXT,
+    metadata_type   TEXT
+)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+    SELECT d.id, d.title, jsonb_typeof(d.metadata)
+    FROM cerefox_documents d
+    WHERE d.metadata IS NOT NULL AND jsonb_typeof(d.metadata) <> 'object'
+    ORDER BY d.title;
 $$;
 
 -- ── cerefox_content_format_stats ─────────────────────────────────────────────

package/dist/server-assets/db/schema.sql

@@ -5,7 +5,7 @@
 -- Requires extensions: vector (pgvector), uuid-ossp
 -- These are enabled at the top of db_deploy.py before this file is applied.
 --
--- @version: 0.12.0
+-- @version: 0.12.2
 -- The `@version` marker above is read by the schema-version-mismatch banner
 -- (see /api/v1/schema-version). Bump it whenever schema.sql OR rpcs.sql
 -- changes in a way that requires `cerefox server deploy` to be re-run —
@@ -42,7 +42,15 @@ CREATE TABLE IF NOT EXISTS cerefox_documents (
     source_path     TEXT,
     -- SHA-256 of raw markdown content; used for deduplication
     content_hash    TEXT        NOT NULL,
-    metadata        JSONB       NOT NULL DEFAULT '{}'::jsonb,
+    -- #212 (0.12.2): must be a JSON OBJECT — jsonb accepts any JSON value,
+    -- but every reader assumes an object, and non-object values were silently
+    -- destroyed by read-modify-write paths. The table-level CHECK closes all
+    -- current AND future direct writers at once; existing databases get it as
+    -- NOT VALID via migration 0026 (legacy rows survive until repaired with
+    -- `document set-metadata --replace`, which the constraint then validates).
+    metadata        JSONB       NOT NULL DEFAULT '{}'::jsonb
+                    CONSTRAINT cerefox_documents_metadata_object
+                    CHECK (jsonb_typeof(metadata) = 'object'),
     chunk_count     INT         NOT NULL DEFAULT 0,
     total_chars     INT         NOT NULL DEFAULT 0,
     -- review_status: human governance flag. 'approved' = validated by human,

package/docs/guides/cli.md

@@ -226,6 +226,12 @@ cerefox document list [OPTIONS]
 
 **Purpose**: update a document's title and/or metadata in place, without re-ingesting content.
 
+> **v1.7.1 (#212)**: a title-only edit no longer writes `metadata` at all, and
+> the command refuses to patch a document whose stored metadata is not a JSON
+> object (a legacy state older writes could create) instead of destroying it —
+> repair such a row with `cerefox document set-metadata <id> --replace --json
+> '<object>'`. `cerefox doctor` lists any rows in that state.
+
 **Synopsis**:
 ```
 cerefox document edit [OPTIONS] DOCUMENT_ID
@@ -341,6 +347,20 @@ cerefox document set-projects <doc-id> --clear
 
 ---
 
+### `cerefox document dead-links`
+
+**Purpose**: whole-KB sweep for `[Text](uuid)` links whose target document no longer exists (phase 2 of link integrity, #214; v1.7.1, needs schema 0.12.2).
+
+**Synopsis**: `cerefox document dead-links [--json]`
+
+The write-time guard (v1.7.0) validates only links a write *introduces* — deliberately, so a target purged after linking cannot make its linkers unwritable. This command finds those legacy dead links on demand. A trashed target still exists and is **not** reported; trashed **linker** documents are also excluded (inert until restored — a restore re-enters them into the next sweep). Full chunk scan server-side (one RPC call); run on demand, not part of `doctor`.
+
+**Fix each hit** by editing the linking document: correct the id, remove the link, or backtick it as an example. Full linking overview: [`linking.md`](linking.md).
+
+**MCP equivalent**: none (maintenance verb).
+
+---
+
 ### `cerefox document restore`
 
 **Purpose**: restore a soft-deleted (trashed) document back to active.
@@ -806,6 +826,7 @@ surface).
 | `document get` | `cerefox_get_document` | ✅ |
 | `document list` | `cerefox_metadata_search` (scope by `project_name` / metadata / time) | ✅ as of this change. Unscoped whole-KB listing has no MCP path by design (scope it) |
 | `document edit` (title / metadata in place) | — | 🔒 intentional: a human/web-parity convenience. Agents update title+metadata deterministically via `cerefox_ingest` (with `document_id`); a metadata-only edit isn't a needed agent primitive |
+| `document dead-links` | — | 🔒 intentional: a maintenance sweep for the operator (v1.7.1, #214 phase 2); agents encounter dead links through the write-time guard instead |
 | `document delete` (soft-delete) | `cerefox_delete_document` | ✅ v1.7.0 (#208). MCP requires the caller's read-hash; the CLI confirms interactively instead |
 | `document restore` | `cerefox_restore_document` | ✅ v1.7.0 (#210). Permanent purge remains web-UI-only |
 | `document version list` | `cerefox_list_versions` | ✅ |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Cerefox — user-owned shared memory for AI agents. CLI + stdio MCP server + web UI + ingestion for a knowledge base on your own Supabase project (or fully self-hosted with Cerefox Local).",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",