@cerefox/memory 1.7.0 → 1.8.0

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.8.0";
 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.8.0", CEREFOX_VERSION = "1.8.0", 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
@@ -72951,7 +72988,13 @@ async function migrationStatus(opts) {
 }
 async function runDbMigrate(opts) {
   const log = opts.log ?? (() => {});
-  const sql = src_default(opts.dbUrl, { prepare: false, onnotice: () => {} });
+  const sql = src_default(opts.dbUrl, {
+    prepare: false,
+    onnotice: (n) => {
+      if (n.message)
+        log(`   ↳ ${n.message}`);
+    }
+  });
   try {
     await sql.unsafe(BOOTSTRAP_MIGRATIONS_SQL);
     const allFiles = listMigrationFiles(opts.assets.migrationsDir);
@@ -73043,7 +73086,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 +73301,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 +73321,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 +73339,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 +73382,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 +73400,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 +73460,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 +73538,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 +73575,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 +73625,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 +73637,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 +73671,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 +77493,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 +77505,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 +77552,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 +77795,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 +77824,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({
@@ -77757,6 +77866,10 @@ async function action16(options) {
     }
     if (remediation) {
       println(cErr.yellow("→ " + remediation));
+      const configDir = (process.env.CEREFOX_CONFIG_DIR ?? "").trim();
+      if (configDir) {
+        println(cErr.dim(`  (this doctor ran against CEREFOX_CONFIG_DIR=${configDir} — ` + `prefix the command above the same way, or use your environment alias, ` + `or a bare \`cerefox\` will act on your DEFAULT environment instead)`));
+      }
       println("");
     }
   }
@@ -77779,13 +77892,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 +77936,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 +78072,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 +78169,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 +78833,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 +78924,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 +79027,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 +79102,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 +79433,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 +79542,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 +79604,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 +79638,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 +79673,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 +79720,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 +79752,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 +79815,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 +79841,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 +79931,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 +79939,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 +80066,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 +80096,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 +80231,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 +80256,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 +80422,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 +80469,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 +80522,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 +80541,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 +80562,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 +80595,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 +80606,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 +85182,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 +86450,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);