@cerefox/memory 1.0.8 → 1.1.0-beta.2

package/dist/bin/cerefox.js

@@ -5340,7 +5340,7 @@ var init_cli_core = __esm(() => {
   init_prompts();
 });
 
-// ../../node_modules/.bun/commander@12.1.0/node_modules/commander/lib/error.js
+// ../../node_modules/.bun/commander@14.0.3/node_modules/commander/lib/error.js
 var require_error = __commonJS((exports) => {
   class CommanderError extends Error {
     constructor(exitCode, code, message) {
@@ -5364,7 +5364,7 @@ var require_error = __commonJS((exports) => {
   exports.InvalidArgumentError = InvalidArgumentError;
 });
 
-// ../../node_modules/.bun/commander@12.1.0/node_modules/commander/lib/argument.js
+// ../../node_modules/.bun/commander@14.0.3/node_modules/commander/lib/argument.js
 var require_argument = __commonJS((exports) => {
   var { InvalidArgumentError } = require_error();
 
@@ -5390,7 +5390,7 @@ var require_argument = __commonJS((exports) => {
           this._name = name;
           break;
       }
-      if (this._name.length > 3 && this._name.slice(-3) === "...") {
+      if (this._name.endsWith("...")) {
         this.variadic = true;
         this._name = this._name.slice(0, -3);
       }
@@ -5398,11 +5398,12 @@ var require_argument = __commonJS((exports) => {
     name() {
       return this._name;
     }
-    _concatValue(value, previous) {
+    _collectValue(value, previous) {
       if (previous === this.defaultValue || !Array.isArray(previous)) {
         return [value];
       }
-      return previous.concat(value);
+      previous.push(value);
+      return previous;
     }
     default(value, description) {
       this.defaultValue = value;
@@ -5420,7 +5421,7 @@ var require_argument = __commonJS((exports) => {
           throw new InvalidArgumentError(`Allowed choices are ${this.argChoices.join(", ")}.`);
         }
         if (this.variadic) {
-          return this._concatValue(arg, previous);
+          return this._collectValue(arg, previous);
         }
         return arg;
       };
@@ -5443,17 +5444,21 @@ var require_argument = __commonJS((exports) => {
   exports.humanReadableArgName = humanReadableArgName;
 });
 
-// ../../node_modules/.bun/commander@12.1.0/node_modules/commander/lib/help.js
+// ../../node_modules/.bun/commander@14.0.3/node_modules/commander/lib/help.js
 var require_help = __commonJS((exports) => {
   var { humanReadableArgName } = require_argument();
 
   class Help {
     constructor() {
       this.helpWidth = undefined;
+      this.minWidthToWrap = 40;
       this.sortSubcommands = false;
       this.sortOptions = false;
       this.showGlobalOptions = false;
     }
+    prepareContext(contextOptions) {
+      this.helpWidth = this.helpWidth ?? contextOptions.helpWidth ?? 80;
+    }
     visibleCommands(cmd) {
       const visibleCommands = cmd.commands.filter((cmd2) => !cmd2._hidden);
       const helpCommand = cmd._getHelpCommand();
@@ -5528,22 +5533,22 @@ var require_help = __commonJS((exports) => {
     }
     longestSubcommandTermLength(cmd, helper) {
       return helper.visibleCommands(cmd).reduce((max, command) => {
-        return Math.max(max, helper.subcommandTerm(command).length);
+        return Math.max(max, this.displayWidth(helper.styleSubcommandTerm(helper.subcommandTerm(command))));
       }, 0);
     }
     longestOptionTermLength(cmd, helper) {
       return helper.visibleOptions(cmd).reduce((max, option) => {
-        return Math.max(max, helper.optionTerm(option).length);
+        return Math.max(max, this.displayWidth(helper.styleOptionTerm(helper.optionTerm(option))));
       }, 0);
     }
     longestGlobalOptionTermLength(cmd, helper) {
       return helper.visibleGlobalOptions(cmd).reduce((max, option) => {
-        return Math.max(max, helper.optionTerm(option).length);
+        return Math.max(max, this.displayWidth(helper.styleOptionTerm(helper.optionTerm(option))));
       }, 0);
     }
     longestArgumentTermLength(cmd, helper) {
       return helper.visibleArguments(cmd).reduce((max, argument) => {
-        return Math.max(max, helper.argumentTerm(argument).length);
+        return Math.max(max, this.displayWidth(helper.styleArgumentTerm(helper.argumentTerm(argument))));
       }, 0);
     }
     commandUsage(cmd) {
@@ -5581,7 +5586,11 @@ var require_help = __commonJS((exports) => {
         extraInfo.push(`env: ${option.envVar}`);
       }
       if (extraInfo.length > 0) {
-        return `${option.description} (${extraInfo.join(", ")})`;
+        const extraDescription = `(${extraInfo.join(", ")})`;
+        if (option.description) {
+          return `${option.description} ${extraDescription}`;
+        }
+        return extraDescription;
       }
       return option.description;
     }
@@ -5594,105 +5603,205 @@ var require_help = __commonJS((exports) => {
         extraInfo.push(`default: ${argument.defaultValueDescription || JSON.stringify(argument.defaultValue)}`);
       }
       if (extraInfo.length > 0) {
-        const extraDescripton = `(${extraInfo.join(", ")})`;
+        const extraDescription = `(${extraInfo.join(", ")})`;
         if (argument.description) {
-          return `${argument.description} ${extraDescripton}`;
+          return `${argument.description} ${extraDescription}`;
         }
-        return extraDescripton;
+        return extraDescription;
       }
       return argument.description;
     }
+    formatItemList(heading, items, helper) {
+      if (items.length === 0)
+        return [];
+      return [helper.styleTitle(heading), ...items, ""];
+    }
+    groupItems(unsortedItems, visibleItems, getGroup) {
+      const result = new Map;
+      unsortedItems.forEach((item) => {
+        const group = getGroup(item);
+        if (!result.has(group))
+          result.set(group, []);
+      });
+      visibleItems.forEach((item) => {
+        const group = getGroup(item);
+        if (!result.has(group)) {
+          result.set(group, []);
+        }
+        result.get(group).push(item);
+      });
+      return result;
+    }
     formatHelp(cmd, helper) {
       const termWidth = helper.padWidth(cmd, helper);
-      const helpWidth = helper.helpWidth || 80;
-      const itemIndentWidth = 2;
-      const itemSeparatorWidth = 2;
-      function formatItem(term, description) {
-        if (description) {
-          const fullText = `${term.padEnd(termWidth + itemSeparatorWidth)}${description}`;
-          return helper.wrap(fullText, helpWidth - itemIndentWidth, termWidth + itemSeparatorWidth);
-        }
-        return term;
+      const helpWidth = helper.helpWidth ?? 80;
+      function callFormatItem(term, description) {
+        return helper.formatItem(term, termWidth, description, helper);
       }
-      function formatList(textArray) {
-        return textArray.join(`
-`).replace(/^/gm, " ".repeat(itemIndentWidth));
-      }
-      let output = [`Usage: ${helper.commandUsage(cmd)}`, ""];
+      let output = [
+        `${helper.styleTitle("Usage:")} ${helper.styleUsage(helper.commandUsage(cmd))}`,
+        ""
+      ];
       const commandDescription = helper.commandDescription(cmd);
       if (commandDescription.length > 0) {
         output = output.concat([
-          helper.wrap(commandDescription, helpWidth, 0),
+          helper.boxWrap(helper.styleCommandDescription(commandDescription), helpWidth),
           ""
         ]);
       }
       const argumentList = helper.visibleArguments(cmd).map((argument) => {
-        return formatItem(helper.argumentTerm(argument), helper.argumentDescription(argument));
+        return callFormatItem(helper.styleArgumentTerm(helper.argumentTerm(argument)), helper.styleArgumentDescription(helper.argumentDescription(argument)));
       });
-      if (argumentList.length > 0) {
-        output = output.concat(["Arguments:", formatList(argumentList), ""]);
-      }
-      const optionList = helper.visibleOptions(cmd).map((option) => {
-        return formatItem(helper.optionTerm(option), helper.optionDescription(option));
+      output = output.concat(this.formatItemList("Arguments:", argumentList, helper));
+      const optionGroups = this.groupItems(cmd.options, helper.visibleOptions(cmd), (option) => option.helpGroupHeading ?? "Options:");
+      optionGroups.forEach((options, group) => {
+        const optionList = options.map((option) => {
+          return callFormatItem(helper.styleOptionTerm(helper.optionTerm(option)), helper.styleOptionDescription(helper.optionDescription(option)));
+        });
+        output = output.concat(this.formatItemList(group, optionList, helper));
       });
-      if (optionList.length > 0) {
-        output = output.concat(["Options:", formatList(optionList), ""]);
-      }
-      if (this.showGlobalOptions) {
+      if (helper.showGlobalOptions) {
         const globalOptionList = helper.visibleGlobalOptions(cmd).map((option) => {
-          return formatItem(helper.optionTerm(option), helper.optionDescription(option));
+          return callFormatItem(helper.styleOptionTerm(helper.optionTerm(option)), helper.styleOptionDescription(helper.optionDescription(option)));
         });
-        if (globalOptionList.length > 0) {
-          output = output.concat([
-            "Global Options:",
-            formatList(globalOptionList),
-            ""
-          ]);
-        }
+        output = output.concat(this.formatItemList("Global Options:", globalOptionList, helper));
       }
-      const commandList = helper.visibleCommands(cmd).map((cmd2) => {
-        return formatItem(helper.subcommandTerm(cmd2), helper.subcommandDescription(cmd2));
+      const commandGroups = this.groupItems(cmd.commands, helper.visibleCommands(cmd), (sub) => sub.helpGroup() || "Commands:");
+      commandGroups.forEach((commands, group) => {
+        const commandList = commands.map((sub) => {
+          return callFormatItem(helper.styleSubcommandTerm(helper.subcommandTerm(sub)), helper.styleSubcommandDescription(helper.subcommandDescription(sub)));
+        });
+        output = output.concat(this.formatItemList(group, commandList, helper));
       });
-      if (commandList.length > 0) {
-        output = output.concat(["Commands:", formatList(commandList), ""]);
-      }
       return output.join(`
 `);
     }
+    displayWidth(str) {
+      return stripColor(str).length;
+    }
+    styleTitle(str) {
+      return str;
+    }
+    styleUsage(str) {
+      return str.split(" ").map((word) => {
+        if (word === "[options]")
+          return this.styleOptionText(word);
+        if (word === "[command]")
+          return this.styleSubcommandText(word);
+        if (word[0] === "[" || word[0] === "<")
+          return this.styleArgumentText(word);
+        return this.styleCommandText(word);
+      }).join(" ");
+    }
+    styleCommandDescription(str) {
+      return this.styleDescriptionText(str);
+    }
+    styleOptionDescription(str) {
+      return this.styleDescriptionText(str);
+    }
+    styleSubcommandDescription(str) {
+      return this.styleDescriptionText(str);
+    }
+    styleArgumentDescription(str) {
+      return this.styleDescriptionText(str);
+    }
+    styleDescriptionText(str) {
+      return str;
+    }
+    styleOptionTerm(str) {
+      return this.styleOptionText(str);
+    }
+    styleSubcommandTerm(str) {
+      return str.split(" ").map((word) => {
+        if (word === "[options]")
+          return this.styleOptionText(word);
+        if (word[0] === "[" || word[0] === "<")
+          return this.styleArgumentText(word);
+        return this.styleSubcommandText(word);
+      }).join(" ");
+    }
+    styleArgumentTerm(str) {
+      return this.styleArgumentText(str);
+    }
+    styleOptionText(str) {
+      return str;
+    }
+    styleArgumentText(str) {
+      return str;
+    }
+    styleSubcommandText(str) {
+      return str;
+    }
+    styleCommandText(str) {
+      return str;
+    }
     padWidth(cmd, helper) {
       return Math.max(helper.longestOptionTermLength(cmd, helper), helper.longestGlobalOptionTermLength(cmd, helper), helper.longestSubcommandTermLength(cmd, helper), helper.longestArgumentTermLength(cmd, helper));
     }
-    wrap(str, width, indent, minColumnWidth = 40) {
-      const indents = " \\f\\t\\v   -   　\uFEFF";
-      const manualIndent = new RegExp(`[\\n][${indents}]+`);
-      if (str.match(manualIndent))
-        return str;
-      const columnWidth = width - indent;
-      if (columnWidth < minColumnWidth)
+    preformatted(str) {
+      return /\n[^\S\r\n]/.test(str);
+    }
+    formatItem(term, termWidth, description, helper) {
+      const itemIndent = 2;
+      const itemIndentStr = " ".repeat(itemIndent);
+      if (!description)
+        return itemIndentStr + term;
+      const paddedTerm = term.padEnd(termWidth + term.length - helper.displayWidth(term));
+      const spacerWidth = 2;
+      const helpWidth = this.helpWidth ?? 80;
+      const remainingWidth = helpWidth - termWidth - spacerWidth - itemIndent;
+      let formattedDescription;
+      if (remainingWidth < this.minWidthToWrap || helper.preformatted(description)) {
+        formattedDescription = description;
+      } else {
+        const wrappedDescription = helper.boxWrap(description, remainingWidth);
+        formattedDescription = wrappedDescription.replace(/\n/g, `
+` + " ".repeat(termWidth + spacerWidth));
+      }
+      return itemIndentStr + paddedTerm + " ".repeat(spacerWidth) + formattedDescription.replace(/\n/g, `
+${itemIndentStr}`);
+    }
+    boxWrap(str, width) {
+      if (width < this.minWidthToWrap)
         return str;
-      const leadingStr = str.slice(0, indent);
-      const columnText = str.slice(indent).replace(`\r
-`, `
-`);
-      const indentString = " ".repeat(indent);
-      const zeroWidthSpace = "​";
-      const breaks = `\\s${zeroWidthSpace}`;
-      const regex = new RegExp(`
-|.{1,${columnWidth - 1}}([${breaks}]|$)|[^${breaks}]+?([${breaks}]|$)`, "g");
-      const lines = columnText.match(regex) || [];
-      return leadingStr + lines.map((line, i) => {
-        if (line === `
-`)
-          return "";
-        return (i > 0 ? indentString : "") + line.trimEnd();
-      }).join(`
+      const rawLines = str.split(/\r\n|\n/);
+      const chunkPattern = /[\s]*[^\s]+/g;
+      const wrappedLines = [];
+      rawLines.forEach((line) => {
+        const chunks = line.match(chunkPattern);
+        if (chunks === null) {
+          wrappedLines.push("");
+          return;
+        }
+        let sumChunks = [chunks.shift()];
+        let sumWidth = this.displayWidth(sumChunks[0]);
+        chunks.forEach((chunk) => {
+          const visibleWidth = this.displayWidth(chunk);
+          if (sumWidth + visibleWidth <= width) {
+            sumChunks.push(chunk);
+            sumWidth += visibleWidth;
+            return;
+          }
+          wrappedLines.push(sumChunks.join(""));
+          const nextChunk = chunk.trimStart();
+          sumChunks = [nextChunk];
+          sumWidth = this.displayWidth(nextChunk);
+        });
+        wrappedLines.push(sumChunks.join(""));
+      });
+      return wrappedLines.join(`
 `);
     }
   }
+  function stripColor(str) {
+    const sgrPattern = /\x1b\[\d*(;\d*)*m/g;
+    return str.replace(sgrPattern, "");
+  }
   exports.Help = Help;
+  exports.stripColor = stripColor;
 });
 
-// ../../node_modules/.bun/commander@12.1.0/node_modules/commander/lib/option.js
+// ../../node_modules/.bun/commander@14.0.3/node_modules/commander/lib/option.js
 var require_option = __commonJS((exports) => {
   var { InvalidArgumentError } = require_error();
 
@@ -5720,6 +5829,7 @@ var require_option = __commonJS((exports) => {
       this.argChoices = undefined;
       this.conflictsWith = [];
       this.implied = undefined;
+      this.helpGroupHeading = undefined;
     }
     default(value, description) {
       this.defaultValue = value;
@@ -5758,11 +5868,12 @@ var require_option = __commonJS((exports) => {
       this.hidden = !!hide;
       return this;
     }
-    _concatValue(value, previous) {
+    _collectValue(value, previous) {
       if (previous === this.defaultValue || !Array.isArray(previous)) {
         return [value];
       }
-      return previous.concat(value);
+      previous.push(value);
+      return previous;
     }
     choices(values) {
       this.argChoices = values.slice();
@@ -5771,7 +5882,7 @@ var require_option = __commonJS((exports) => {
           throw new InvalidArgumentError(`Allowed choices are ${this.argChoices.join(", ")}.`);
         }
         if (this.variadic) {
-          return this._concatValue(arg, previous);
+          return this._collectValue(arg, previous);
         }
         return arg;
       };
@@ -5784,7 +5895,14 @@ var require_option = __commonJS((exports) => {
       return this.short.replace(/^-/, "");
     }
     attributeName() {
-      return camelcase(this.name().replace(/^no-/, ""));
+      if (this.negate) {
+        return camelcase(this.name().replace(/^no-/, ""));
+      }
+      return camelcase(this.name());
+    }
+    helpGroup(heading) {
+      this.helpGroupHeading = heading;
+      return this;
     }
     is(arg) {
       return this.short === arg || this.long === arg;
@@ -5829,21 +5947,45 @@ var require_option = __commonJS((exports) => {
   function splitOptionFlags(flags) {
     let shortFlag;
     let longFlag;
-    const flagParts = flags.split(/[ |,]+/);
-    if (flagParts.length > 1 && !/^[[<]/.test(flagParts[1]))
+    const shortFlagExp = /^-[^-]$/;
+    const longFlagExp = /^--[^-]/;
+    const flagParts = flags.split(/[ |,]+/).concat("guard");
+    if (shortFlagExp.test(flagParts[0]))
+      shortFlag = flagParts.shift();
+    if (longFlagExp.test(flagParts[0]))
+      longFlag = flagParts.shift();
+    if (!shortFlag && shortFlagExp.test(flagParts[0]))
       shortFlag = flagParts.shift();
-    longFlag = flagParts.shift();
-    if (!shortFlag && /^-[^-]$/.test(longFlag)) {
+    if (!shortFlag && longFlagExp.test(flagParts[0])) {
       shortFlag = longFlag;
-      longFlag = undefined;
-    }
+      longFlag = flagParts.shift();
+    }
+    if (flagParts[0].startsWith("-")) {
+      const unsupportedFlag = flagParts[0];
+      const baseError = `option creation failed due to '${unsupportedFlag}' in option flags '${flags}'`;
+      if (/^-[^-][^-]/.test(unsupportedFlag))
+        throw new Error(`${baseError}
+- a short flag is a single dash and a single character
+  - either use a single dash and a single character (for a short flag)
+  - or use a double dash for a long option (and can have two, like '--ws, --workspace')`);
+      if (shortFlagExp.test(unsupportedFlag))
+        throw new Error(`${baseError}
+- too many short flags`);
+      if (longFlagExp.test(unsupportedFlag))
+        throw new Error(`${baseError}
+- too many long flags`);
+      throw new Error(`${baseError}
+- unrecognised flag format`);
+    }
+    if (shortFlag === undefined && longFlag === undefined)
+      throw new Error(`option creation failed due to no flags found in '${flags}'.`);
     return { shortFlag, longFlag };
   }
   exports.Option = Option;
   exports.DualOptions = DualOptions;
 });
 
-// ../../node_modules/.bun/commander@12.1.0/node_modules/commander/lib/suggestSimilar.js
+// ../../node_modules/.bun/commander@14.0.3/node_modules/commander/lib/suggestSimilar.js
 var require_suggestSimilar = __commonJS((exports) => {
   var maxDistance = 3;
   function editDistance(a, b) {
@@ -5916,7 +6058,7 @@ var require_suggestSimilar = __commonJS((exports) => {
   exports.suggestSimilar = suggestSimilar;
 });
 
-// ../../node_modules/.bun/commander@12.1.0/node_modules/commander/lib/command.js
+// ../../node_modules/.bun/commander@14.0.3/node_modules/commander/lib/command.js
 var require_command = __commonJS((exports) => {
   var EventEmitter = __require("node:events").EventEmitter;
   var childProcess = __require("node:child_process");
@@ -5925,7 +6067,7 @@ var require_command = __commonJS((exports) => {
   var process2 = __require("node:process");
   var { Argument, humanReadableArgName } = require_argument();
   var { CommanderError } = require_error();
-  var { Help } = require_help();
+  var { Help, stripColor } = require_help();
   var { Option, DualOptions } = require_option();
   var { suggestSimilar } = require_suggestSimilar();
 
@@ -5936,7 +6078,7 @@ var require_command = __commonJS((exports) => {
       this.options = [];
       this.parent = null;
       this._allowUnknownOption = false;
-      this._allowExcessArguments = true;
+      this._allowExcessArguments = false;
       this.registeredArguments = [];
       this._args = this.registeredArguments;
       this.args = [];
@@ -5963,18 +6105,25 @@ var require_command = __commonJS((exports) => {
       this._lifeCycleHooks = {};
       this._showHelpAfterError = false;
       this._showSuggestionAfterError = true;
+      this._savedState = null;
       this._outputConfiguration = {
         writeOut: (str) => process2.stdout.write(str),
         writeErr: (str) => process2.stderr.write(str),
+        outputError: (str, write) => write(str),
         getOutHelpWidth: () => process2.stdout.isTTY ? process2.stdout.columns : undefined,
         getErrHelpWidth: () => process2.stderr.isTTY ? process2.stderr.columns : undefined,
-        outputError: (str, write) => write(str)
+        getOutHasColors: () => useColor() ?? (process2.stdout.isTTY && process2.stdout.hasColors?.()),
+        getErrHasColors: () => useColor() ?? (process2.stderr.isTTY && process2.stderr.hasColors?.()),
+        stripColor: (str) => stripColor(str)
       };
       this._hidden = false;
       this._helpOption = undefined;
       this._addImplicitHelpCommand = undefined;
       this._helpCommand = undefined;
       this._helpConfiguration = {};
+      this._helpGroupHeading = undefined;
+      this._defaultCommandGroup = undefined;
+      this._defaultOptionGroup = undefined;
     }
     copyInheritedSettings(sourceCommand) {
       this._outputConfiguration = sourceCommand._outputConfiguration;
@@ -6039,7 +6188,10 @@ var require_command = __commonJS((exports) => {
     configureOutput(configuration) {
       if (configuration === undefined)
         return this._outputConfiguration;
-      Object.assign(this._outputConfiguration, configuration);
+      this._outputConfiguration = {
+        ...this._outputConfiguration,
+        ...configuration
+      };
       return this;
     }
     showHelpAfterError(displayHelp = true) {
@@ -6070,12 +6222,12 @@ var require_command = __commonJS((exports) => {
     createArgument(name, description) {
       return new Argument(name, description);
     }
-    argument(name, description, fn, defaultValue) {
+    argument(name, description, parseArg, defaultValue) {
       const argument = this.createArgument(name, description);
-      if (typeof fn === "function") {
-        argument.default(defaultValue).argParser(fn);
+      if (typeof parseArg === "function") {
+        argument.default(defaultValue).argParser(parseArg);
       } else {
-        argument.default(fn);
+        argument.default(parseArg);
       }
       this.addArgument(argument);
       return this;
@@ -6088,7 +6240,7 @@ var require_command = __commonJS((exports) => {
     }
     addArgument(argument) {
       const previousArgument = this.registeredArguments.slice(-1)[0];
-      if (previousArgument && previousArgument.variadic) {
+      if (previousArgument?.variadic) {
         throw new Error(`only the last argument can be variadic '${previousArgument.name()}'`);
       }
       if (argument.required && argument.defaultValue !== undefined && argument.parseArg === undefined) {
@@ -6100,10 +6252,13 @@ var require_command = __commonJS((exports) => {
     helpCommand(enableOrNameAndArgs, description) {
       if (typeof enableOrNameAndArgs === "boolean") {
         this._addImplicitHelpCommand = enableOrNameAndArgs;
+        if (enableOrNameAndArgs && this._defaultCommandGroup) {
+          this._initCommandGroup(this._getHelpCommand());
+        }
         return this;
       }
-      enableOrNameAndArgs = enableOrNameAndArgs ?? "help [command]";
-      const [, helpName, helpArgs] = enableOrNameAndArgs.match(/([^ ]+) *(.*)/);
+      const nameAndArgs = enableOrNameAndArgs ?? "help [command]";
+      const [, helpName, helpArgs] = nameAndArgs.match(/([^ ]+) *(.*)/);
       const helpDescription = description ?? "display help for command";
       const helpCommand = this.createCommand(helpName);
       helpCommand.helpOption(false);
@@ -6113,6 +6268,8 @@ var require_command = __commonJS((exports) => {
         helpCommand.description(helpDescription);
       this._addImplicitHelpCommand = true;
       this._helpCommand = helpCommand;
+      if (enableOrNameAndArgs || description)
+        this._initCommandGroup(helpCommand);
       return this;
     }
     addHelpCommand(helpCommand, deprecatedDescription) {
@@ -6122,6 +6279,7 @@ var require_command = __commonJS((exports) => {
       }
       this._addImplicitHelpCommand = true;
       this._helpCommand = helpCommand;
+      this._initCommandGroup(helpCommand);
       return this;
     }
     _getHelpCommand() {
@@ -6201,6 +6359,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         throw new Error(`Cannot add option '${option.flags}'${this._name && ` to command '${this._name}'`} due to conflicting flag '${matchingFlag}'
 -  already used by option '${matchingOption.flags}'`);
       }
+      this._initOptionGroup(option);
       this.options.push(option);
     }
     _registerCommand(command) {
@@ -6213,6 +6372,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         const newCmd = knownBy(command).join("|");
         throw new Error(`cannot add command '${newCmd}' as already have command '${existingCmd}'`);
       }
+      this._initCommandGroup(command);
       this.commands.push(command);
     }
     addOption(option) {
@@ -6235,7 +6395,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (val !== null && option.parseArg) {
           val = this._callParseArg(option, val, oldValue, invalidValueMessage);
         } else if (val !== null && option.variadic) {
-          val = option._concatValue(val, oldValue);
+          val = option._collectValue(val, oldValue);
         }
         if (val == null) {
           if (option.negate) {
@@ -6400,15 +6560,53 @@ Expecting one of '${allowedValues.join("', '")}'`);
       return userArgs;
     }
     parse(argv, parseOptions) {
+      this._prepareForParse();
       const userArgs = this._prepareUserArgs(argv, parseOptions);
       this._parseCommand([], userArgs);
       return this;
     }
     async parseAsync(argv, parseOptions) {
+      this._prepareForParse();
       const userArgs = this._prepareUserArgs(argv, parseOptions);
       await this._parseCommand([], userArgs);
       return this;
     }
+    _prepareForParse() {
+      if (this._savedState === null) {
+        this.saveStateBeforeParse();
+      } else {
+        this.restoreStateBeforeParse();
+      }
+    }
+    saveStateBeforeParse() {
+      this._savedState = {
+        _name: this._name,
+        _optionValues: { ...this._optionValues },
+        _optionValueSources: { ...this._optionValueSources }
+      };
+    }
+    restoreStateBeforeParse() {
+      if (this._storeOptionsAsProperties)
+        throw new Error(`Can not call parse again when storeOptionsAsProperties is true.
+- either make a new Command for each call to parse, or stop storing options as properties`);
+      this._name = this._savedState._name;
+      this._scriptPath = null;
+      this.rawArgs = [];
+      this._optionValues = { ...this._savedState._optionValues };
+      this._optionValueSources = { ...this._savedState._optionValueSources };
+      this.args = [];
+      this.processedArgs = [];
+    }
+    _checkForMissingExecutable(executableFile, executableDir, subcommandName) {
+      if (fs.existsSync(executableFile))
+        return;
+      const executableDirMessage = executableDir ? `searched for local subcommand relative to directory '${executableDir}'` : "no directory for search for local subcommand, use .executableDir() to supply a custom directory";
+      const executableMissing = `'${executableFile}' does not exist
+ - if '${subcommandName}' is not meant to be an executable command, remove description parameter from '.command()' and use '.description()' instead
+ - if the default executable name is not suitable, use the executableFile option to supply a custom name or path
+ - ${executableDirMessage}`;
+      throw new Error(executableMissing);
+    }
     _executeSubCommand(subcommand, args) {
       args = args.slice();
       let launchWithNode = false;
@@ -6432,7 +6630,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         let resolvedScriptPath;
         try {
           resolvedScriptPath = fs.realpathSync(this._scriptPath);
-        } catch (err) {
+        } catch {
           resolvedScriptPath = this._scriptPath;
         }
         executableDir = path.resolve(path.dirname(resolvedScriptPath), executableDir);
@@ -6458,6 +6656,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           proc = childProcess.spawn(executableFile, args, { stdio: "inherit" });
         }
       } else {
+        this._checkForMissingExecutable(executableFile, executableDir, subcommand._name);
         args.unshift(executableFile);
         args = incrementNodeInspectorPort(process2.execArgv).concat(args);
         proc = childProcess.spawn(process2.execPath, args, { stdio: "inherit" });
@@ -6483,12 +6682,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       });
       proc.on("error", (err) => {
         if (err.code === "ENOENT") {
-          const executableDirMessage = executableDir ? `searched for local subcommand relative to directory '${executableDir}'` : "no directory for search for local subcommand, use .executableDir() to supply a custom directory";
-          const executableMissing = `'${executableFile}' does not exist
- - if '${subcommand._name}' is not meant to be an executable command, remove description parameter from '.command()' and use '.description()' instead
- - if the default executable name is not suitable, use the executableFile option to supply a custom name or path
- - ${executableDirMessage}`;
-          throw new Error(executableMissing);
+          this._checkForMissingExecutable(executableFile, executableDir, subcommand._name);
         } else if (err.code === "EACCES") {
           throw new Error(`'${executableFile}' not executable`);
         }
@@ -6506,6 +6700,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       const subCommand = this._findCommand(commandName);
       if (!subCommand)
         this.help({ error: true });
+      subCommand._prepareForParse();
       let promiseChain;
       promiseChain = this._chainOrCallSubCommandHook(promiseChain, subCommand, "preSubcommand");
       promiseChain = this._chainOrCall(promiseChain, () => {
@@ -6575,7 +6770,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       this.processedArgs = processedArgs;
     }
     _chainOrCall(promise, fn) {
-      if (promise && promise.then && typeof promise.then === "function") {
+      if (promise?.then && typeof promise.then === "function") {
         return promise.then(() => fn());
       }
       return fn();
@@ -6652,7 +6847,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         promiseChain = this._chainOrCallHooks(promiseChain, "postAction");
         return promiseChain;
       }
-      if (this.parent && this.parent.listenerCount(commandEvent)) {
+      if (this.parent?.listenerCount(commandEvent)) {
         checkForUnknownOptions();
         this._processArguments();
         this.parent.emit(commandEvent, operands, unknown);
@@ -6714,24 +6909,31 @@ Expecting one of '${allowedValues.join("', '")}'`);
         cmd._checkForConflictingLocalOptions();
       });
     }
-    parseOptions(argv) {
+    parseOptions(args) {
       const operands = [];
       const unknown = [];
       let dest = operands;
-      const args = argv.slice();
       function maybeOption(arg) {
         return arg.length > 1 && arg[0] === "-";
       }
+      const negativeNumberArg = (arg) => {
+        if (!/^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/.test(arg))
+          return false;
+        return !this._getCommandAndAncestors().some((cmd) => cmd.options.map((opt) => opt.short).some((short) => /^-\d$/.test(short)));
+      };
       let activeVariadicOption = null;
-      while (args.length) {
-        const arg = args.shift();
+      let activeGroup = null;
+      let i = 0;
+      while (i < args.length || activeGroup) {
+        const arg = activeGroup ?? args[i++];
+        activeGroup = null;
         if (arg === "--") {
           if (dest === unknown)
             dest.push(arg);
-          dest.push(...args);
+          dest.push(...args.slice(i));
           break;
         }
-        if (activeVariadicOption && !maybeOption(arg)) {
+        if (activeVariadicOption && (!maybeOption(arg) || negativeNumberArg(arg))) {
           this.emit(`option:${activeVariadicOption.name()}`, arg);
           continue;
         }
@@ -6740,14 +6942,14 @@ Expecting one of '${allowedValues.join("', '")}'`);
           const option = this._findOption(arg);
           if (option) {
             if (option.required) {
-              const value = args.shift();
+              const value = args[i++];
               if (value === undefined)
                 this.optionMissingArgument(option);
               this.emit(`option:${option.name()}`, value);
             } else if (option.optional) {
               let value = null;
-              if (args.length > 0 && !maybeOption(args[0])) {
-                value = args.shift();
+              if (i < args.length && (!maybeOption(args[i]) || negativeNumberArg(args[i]))) {
+                value = args[i++];
               }
               this.emit(`option:${option.name()}`, value);
             } else {
@@ -6764,7 +6966,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
               this.emit(`option:${option.name()}`, arg.slice(2));
             } else {
               this.emit(`option:${option.name()}`);
-              args.unshift(`-${arg.slice(2)}`);
+              activeGroup = `-${arg.slice(2)}`;
             }
             continue;
           }
@@ -6777,31 +6979,24 @@ Expecting one of '${allowedValues.join("', '")}'`);
             continue;
           }
         }
-        if (maybeOption(arg)) {
+        if (dest === operands && maybeOption(arg) && !(this.commands.length === 0 && negativeNumberArg(arg))) {
           dest = unknown;
         }
         if ((this._enablePositionalOptions || this._passThroughOptions) && operands.length === 0 && unknown.length === 0) {
           if (this._findCommand(arg)) {
             operands.push(arg);
-            if (args.length > 0)
-              unknown.push(...args);
+            unknown.push(...args.slice(i));
             break;
           } else if (this._getHelpCommand() && arg === this._getHelpCommand().name()) {
-            operands.push(arg);
-            if (args.length > 0)
-              operands.push(...args);
+            operands.push(arg, ...args.slice(i));
             break;
           } else if (this._defaultCommandName) {
-            unknown.push(arg);
-            if (args.length > 0)
-              unknown.push(...args);
+            unknown.push(arg, ...args.slice(i));
             break;
           }
         }
         if (this._passThroughOptions) {
-          dest.push(arg);
-          if (args.length > 0)
-            dest.push(...args);
+          dest.push(arg, ...args.slice(i));
           break;
         }
         dest.push(arg);
@@ -7012,6 +7207,32 @@ Expecting one of '${allowedValues.join("', '")}'`);
       this._name = str;
       return this;
     }
+    helpGroup(heading) {
+      if (heading === undefined)
+        return this._helpGroupHeading ?? "";
+      this._helpGroupHeading = heading;
+      return this;
+    }
+    commandsGroup(heading) {
+      if (heading === undefined)
+        return this._defaultCommandGroup ?? "";
+      this._defaultCommandGroup = heading;
+      return this;
+    }
+    optionsGroup(heading) {
+      if (heading === undefined)
+        return this._defaultOptionGroup ?? "";
+      this._defaultOptionGroup = heading;
+      return this;
+    }
+    _initOptionGroup(option) {
+      if (this._defaultOptionGroup && !option.helpGroupHeading)
+        option.helpGroup(this._defaultOptionGroup);
+    }
+    _initCommandGroup(cmd) {
+      if (this._defaultCommandGroup && !cmd.helpGroup())
+        cmd.helpGroup(this._defaultCommandGroup);
+    }
     nameFromFilename(filename) {
       this._name = path.basename(filename, path.extname(filename));
       return this;
@@ -7024,23 +7245,38 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
     helpInformation(contextOptions) {
       const helper = this.createHelp();
-      if (helper.helpWidth === undefined) {
-        helper.helpWidth = contextOptions && contextOptions.error ? this._outputConfiguration.getErrHelpWidth() : this._outputConfiguration.getOutHelpWidth();
-      }
-      return helper.formatHelp(this, helper);
+      const context = this._getOutputContext(contextOptions);
+      helper.prepareContext({
+        error: context.error,
+        helpWidth: context.helpWidth,
+        outputHasColors: context.hasColors
+      });
+      const text = helper.formatHelp(this, helper);
+      if (context.hasColors)
+        return text;
+      return this._outputConfiguration.stripColor(text);
     }
-    _getHelpContext(contextOptions) {
+    _getOutputContext(contextOptions) {
       contextOptions = contextOptions || {};
-      const context = { error: !!contextOptions.error };
-      let write;
-      if (context.error) {
-        write = (arg) => this._outputConfiguration.writeErr(arg);
+      const error = !!contextOptions.error;
+      let baseWrite;
+      let hasColors;
+      let helpWidth;
+      if (error) {
+        baseWrite = (str) => this._outputConfiguration.writeErr(str);
+        hasColors = this._outputConfiguration.getErrHasColors();
+        helpWidth = this._outputConfiguration.getErrHelpWidth();
       } else {
-        write = (arg) => this._outputConfiguration.writeOut(arg);
-      }
-      context.write = contextOptions.write || write;
-      context.command = this;
-      return context;
+        baseWrite = (str) => this._outputConfiguration.writeOut(str);
+        hasColors = this._outputConfiguration.getOutHasColors();
+        helpWidth = this._outputConfiguration.getOutHelpWidth();
+      }
+      const write = (str) => {
+        if (!hasColors)
+          str = this._outputConfiguration.stripColor(str);
+        return baseWrite(str);
+      };
+      return { error, write, hasColors, helpWidth };
     }
     outputHelp(contextOptions) {
       let deprecatedCallback;
@@ -7048,35 +7284,44 @@ Expecting one of '${allowedValues.join("', '")}'`);
         deprecatedCallback = contextOptions;
         contextOptions = undefined;
       }
-      const context = this._getHelpContext(contextOptions);
-      this._getCommandAndAncestors().reverse().forEach((command) => command.emit("beforeAllHelp", context));
-      this.emit("beforeHelp", context);
-      let helpInformation = this.helpInformation(context);
+      const outputContext = this._getOutputContext(contextOptions);
+      const eventContext = {
+        error: outputContext.error,
+        write: outputContext.write,
+        command: this
+      };
+      this._getCommandAndAncestors().reverse().forEach((command) => command.emit("beforeAllHelp", eventContext));
+      this.emit("beforeHelp", eventContext);
+      let helpInformation = this.helpInformation({ error: outputContext.error });
       if (deprecatedCallback) {
         helpInformation = deprecatedCallback(helpInformation);
         if (typeof helpInformation !== "string" && !Buffer.isBuffer(helpInformation)) {
           throw new Error("outputHelp callback must return a string or a Buffer");
         }
       }
-      context.write(helpInformation);
+      outputContext.write(helpInformation);
       if (this._getHelpOption()?.long) {
         this.emit(this._getHelpOption().long);
       }
-      this.emit("afterHelp", context);
-      this._getCommandAndAncestors().forEach((command) => command.emit("afterAllHelp", context));
+      this.emit("afterHelp", eventContext);
+      this._getCommandAndAncestors().forEach((command) => command.emit("afterAllHelp", eventContext));
     }
     helpOption(flags, description) {
       if (typeof flags === "boolean") {
         if (flags) {
-          this._helpOption = this._helpOption ?? undefined;
+          if (this._helpOption === null)
+            this._helpOption = undefined;
+          if (this._defaultOptionGroup) {
+            this._initOptionGroup(this._getHelpOption());
+          }
         } else {
           this._helpOption = null;
         }
         return this;
       }
-      flags = flags ?? "-h, --help";
-      description = description ?? "display help for command";
-      this._helpOption = this.createOption(flags, description);
+      this._helpOption = this.createOption(flags ?? "-h, --help", description ?? "display help for command");
+      if (flags || description)
+        this._initOptionGroup(this._helpOption);
       return this;
     }
     _getHelpOption() {
@@ -7087,11 +7332,12 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
     addHelpOption(option) {
       this._helpOption = option;
+      this._initOptionGroup(option);
       return this;
     }
     help(contextOptions) {
       this.outputHelp(contextOptions);
-      let exitCode = process2.exitCode || 0;
+      let exitCode = Number(process2.exitCode ?? 0);
       if (exitCode === 0 && contextOptions && typeof contextOptions !== "function" && contextOptions.error) {
         exitCode = 1;
       }
@@ -7156,10 +7402,18 @@ Expecting one of '${allowedValues.join("', '")}'`);
       return arg;
     });
   }
+  function useColor() {
+    if (process2.env.NO_COLOR || process2.env.FORCE_COLOR === "0" || process2.env.FORCE_COLOR === "false")
+      return false;
+    if (process2.env.FORCE_COLOR || process2.env.CLICOLOR_FORCE !== undefined)
+      return true;
+    return;
+  }
   exports.Command = Command;
+  exports.useColor = useColor;
 });
 
-// ../../node_modules/.bun/commander@12.1.0/node_modules/commander/index.js
+// ../../node_modules/.bun/commander@14.0.3/node_modules/commander/index.js
 var require_commander = __commonJS((exports) => {
   var { Argument } = require_argument();
   var { Command } = require_command();
@@ -7184,7 +7438,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "1.0.8";
+var PKG_VERSION = "1.1.0-beta.2";
 var init_meta = () => {};
 
 // ../../node_modules/.bun/tslib@2.8.1/node_modules/tslib/tslib.js
@@ -23108,9 +23362,12 @@ function loadEnv(opts = {}) {
   } catch {
     return { path: envPath, vars: 0 };
   }
+  const configDirNamed = (env2.CEREFOX_CONFIG_DIR ?? "").trim() !== "";
   let count = 0;
   for (const [k, v] of Object.entries(parseDotenv(content))) {
-    if (env2[k] === undefined) {
+    if (k === "CEREFOX_CONFIG_DIR")
+      continue;
+    if (env2[k] === undefined || configDirNamed) {
       env2[k] = v;
       count++;
     }
@@ -25239,6 +25496,17 @@ function readUnitInterval(name) {
 function getSearchAlpha() {
   return readUnitInterval("CEREFOX_SEARCH_ALPHA") ?? DEFAULT_SEARCH_ALPHA;
 }
+function getConfiguredMinSearchScore() {
+  const explicit = readUnitInterval("CEREFOX_MIN_SEARCH_SCORE");
+  if (explicit !== undefined)
+    return explicit;
+  if (readEnv("CEREFOX_EMBEDDER") === "local")
+    return DEFAULT_MIN_SEARCH_SCORE_LOCAL;
+  return;
+}
+function getConfiguredSearchAlpha() {
+  return readUnitInterval("CEREFOX_SEARCH_ALPHA");
+}
 function getMinSearchScore() {
   const fallback = readEnv("CEREFOX_EMBEDDER") === "local" ? DEFAULT_MIN_SEARCH_SCORE_LOCAL : DEFAULT_MIN_SEARCH_SCORE;
   return readUnitInterval("CEREFOX_MIN_SEARCH_SCORE") ?? fallback;
@@ -54921,6 +55189,36 @@ var init_audit_log = __esm(() => {
   };
 });
 
+// ../../_shared/mcp-tools/feature-flags.ts
+async function relationsEnabled(supabase) {
+  if (cached && Date.now() - cached.at < CACHE_TTL_MS)
+    return cached.value;
+  try {
+    const { data, error: error2 } = await supabase.rpc("cerefox_get_config", {
+      p_key: "relations_enabled"
+    });
+    if (error2)
+      throw new Error(error2.message);
+    const value = String(data ?? "").trim().toLowerCase() === "true";
+    cached = { value, at: Date.now() };
+    return value;
+  } catch {
+    return false;
+  }
+}
+function disabledToolMessage(name) {
+  return `${name} is part of the document-relations feature, which is off by default. ` + `Enable it with: cerefox config set relations_enabled true ` + `(deployment-wide; every access path picks it up).`;
+}
+var RELATION_TOOL_NAMES, CACHE_TTL_MS = 60000, cached = null;
+var init_feature_flags = __esm(() => {
+  RELATION_TOOL_NAMES = new Set([
+    "cerefox_set_relation",
+    "cerefox_delete_relation",
+    "cerefox_get_relations",
+    "cerefox_get_neighbors"
+  ]);
+});
+
 // ../../_shared/mcp-tools/types.ts
 var McpInvalidParams;
 var init_types3 = __esm(() => {
@@ -54932,6 +55230,204 @@ var init_types3 = __esm(() => {
   };
 });
 
+// ../../_shared/mcp-tools/relations.ts
+function requireUuid2(value, field) {
+  const s = typeof value === "string" ? value.trim() : "";
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s)) {
+    throw new McpInvalidParams(`${field} must be a document UUID (got: ${String(value)})`);
+  }
+  return s;
+}
+async function setHandler(supabase, args, ctx) {
+  const source = requireUuid2(args.source_id, "source_id");
+  const target = requireUuid2(args.target_id, "target_id");
+  const relType = typeof args.rel_type === "string" ? args.rel_type.trim() : "";
+  if (!relType)
+    throw new McpInvalidParams("rel_type is required");
+  const { data, error: error2 } = await supabase.rpc("cerefox_set_relation", {
+    p_source_id: source,
+    p_target_id: target,
+    p_rel_type: relType,
+    p_author: args.author ?? "mcp-agent",
+    p_author_type: "agent",
+    p_metadata: args.metadata ?? {}
+  });
+  if (error2)
+    throw new Error(`RPC error: ${error2.message}`);
+  const row = Array.isArray(data) ? data[0] : data;
+  logUsage(supabase, {
+    operation: "set_relation",
+    accessPath: ctx.accessPath,
+    requestor: args.requestor,
+    document_id: source
+  });
+  const both = row?.is_symmetric ? " (symmetric — the reverse edge was written too)" : "";
+  const effect = relType === "supersedes" ? `
+Target marked superseded.` : relType === "contradicts" ? `
+Both documents marked stale.` : "";
+  return `Relation set: ${source} --${relType}--> ${target}${both}.${effect}`;
+}
+async function deleteHandler(supabase, args, ctx) {
+  const source = requireUuid2(args.source_id, "source_id");
+  const target = requireUuid2(args.target_id, "target_id");
+  const relType = typeof args.rel_type === "string" ? args.rel_type.trim() : "";
+  if (!relType)
+    throw new McpInvalidParams("rel_type is required");
+  const { data, error: error2 } = await supabase.rpc("cerefox_delete_relation", {
+    p_source_id: source,
+    p_target_id: target,
+    p_rel_type: relType,
+    p_author: args.author ?? "mcp-agent",
+    p_author_type: "agent"
+  });
+  if (error2)
+    throw new Error(`RPC error: ${error2.message}`);
+  const removed = typeof data === "number" ? data : 0;
+  logUsage(supabase, {
+    operation: "delete_relation",
+    accessPath: ctx.accessPath,
+    requestor: args.requestor,
+    document_id: source
+  });
+  if (removed === 0)
+    return "No such relation — nothing removed.";
+  return `Removed ${removed} relation row(s): ${source} --${relType}--> ${target}. ` + "Lifecycle status is left as-is (a document may be superseded by something else too).";
+}
+async function getRelationsHandler(supabase, args, ctx) {
+  const docId = requireUuid2(args.document_id, "document_id");
+  const { data, error: error2 } = await supabase.rpc("cerefox_get_relations", {
+    p_document_id: docId
+  });
+  if (error2)
+    throw new Error(`RPC error: ${error2.message}`);
+  const rows = data ?? [];
+  logUsage(supabase, {
+    operation: "get_relations",
+    accessPath: ctx.accessPath,
+    requestor: args.requestor,
+    document_id: docId,
+    result_count: rows.length
+  });
+  if (rows.length === 0)
+    return "No relations for this document.";
+  const lines = rows.map((r) => {
+    const arrow = r.direction === "outbound" ? "→" : "←";
+    const life = r.other_lifecycle && r.other_lifecycle !== "active" ? ` [${r.other_lifecycle}]` : "";
+    return `- ${arrow} ${r.rel_type}: ${r.other_title}${life} [id: ${r.other_id}]`;
+  });
+  return `${rows.length} relation(s):
+${lines.join(`
+`)}`;
+}
+async function getNeighborsHandler(supabase, args, ctx) {
+  const docId = requireUuid2(args.document_id, "document_id");
+  const relType = typeof args.rel_type === "string" ? args.rel_type.trim() : "";
+  if (!relType)
+    throw new McpInvalidParams("rel_type is required — pick one type to traverse");
+  const depth = Math.max(1, Math.min(args.depth ?? 1, 5));
+  const { data, error: error2 } = await supabase.rpc("cerefox_get_neighbors", {
+    p_document_id: docId,
+    p_rel_type: relType,
+    p_depth: depth,
+    p_from_time: args.from_time ?? null,
+    p_to_time: args.to_time ?? null,
+    p_limit: Math.max(1, Math.min(args.limit ?? 50, 200))
+  });
+  if (error2)
+    throw new Error(`RPC error: ${error2.message}`);
+  const rows = data ?? [];
+  logUsage(supabase, {
+    operation: "get_neighbors",
+    accessPath: ctx.accessPath,
+    requestor: args.requestor,
+    document_id: docId,
+    result_count: rows.length
+  });
+  if (rows.length === 0)
+    return `No documents reachable via "${relType}".`;
+  const lines = rows.map((r) => {
+    const life = r.lifecycle_status && r.lifecycle_status !== "active" ? ` [${r.lifecycle_status}]` : "";
+    return `- depth ${r.depth} (${r.direction}): ${r.title}${life} [id: ${r.document_id}]`;
+  });
+  return `${rows.length} document(s) via "${relType}":
+${lines.join(`
+`)}`;
+}
+var KNOWN_TYPES = "related_to, references, supersedes, contradicts, duplicates, part_of, follows, reply_to", setRelationTool, deleteRelationTool, getRelationsTool, getNeighborsTool;
+var init_relations = __esm(() => {
+  init_types3();
+  setRelationTool = {
+    name: "cerefox_set_relation",
+    description: "Link two documents with a typed, directed relation (source → target). " + `Known types with behaviour: ${KNOWN_TYPES}. Symmetric types (related_to, ` + "contradicts, duplicates) write both directions. `supersedes` marks the target " + "superseded; `contradicts` marks both stale. Any other type string is accepted " + "and stored, just without special behaviour. Re-setting the same edge updates it.",
+    inputSchema: {
+      type: "object",
+      required: ["source_id", "target_id", "rel_type"],
+      properties: {
+        source_id: { type: "string", description: "UUID of the source document" },
+        target_id: { type: "string", description: "UUID of the target document" },
+        rel_type: {
+          type: "string",
+          description: `Relation type, e.g. one of: ${KNOWN_TYPES}. Free text is allowed.`
+        },
+        metadata: {
+          type: "object",
+          description: "Optional JSON context for the edge (note, confidence, …)"
+        },
+        author: { type: "string", description: "Who is creating this relation" },
+        requestor: { type: "string", description: "Name of the agent making this request" }
+      }
+    },
+    handler: setHandler
+  };
+  deleteRelationTool = {
+    name: "cerefox_delete_relation",
+    description: "Remove a typed relation between two documents. Symmetric types remove both " + "directions. Lifecycle status set by an earlier relation is NOT reverted.",
+    inputSchema: {
+      type: "object",
+      required: ["source_id", "target_id", "rel_type"],
+      properties: {
+        source_id: { type: "string", description: "UUID of the source document" },
+        target_id: { type: "string", description: "UUID of the target document" },
+        rel_type: { type: "string", description: "Relation type to remove" },
+        author: { type: "string", description: "Who is removing this relation" },
+        requestor: { type: "string", description: "Name of the agent making this request" }
+      }
+    },
+    handler: deleteHandler
+  };
+  getRelationsTool = {
+    name: "cerefox_get_relations",
+    description: "List every relation touching a document, in both directions (→ outbound, " + "← inbound). Shows each neighbour's title and lifecycle status, so an agent " + "can tell whether retrieved knowledge has been superseded or contradicted.",
+    inputSchema: {
+      type: "object",
+      required: ["document_id"],
+      properties: {
+        document_id: { type: "string", description: "UUID of the document" },
+        requestor: { type: "string", description: "Name of the agent making this request" }
+      }
+    },
+    handler: getRelationsHandler
+  };
+  getNeighborsTool = {
+    name: "cerefox_get_neighbors",
+    description: "Walk the relation graph outward from a document along ONE relation type. " + "Use after cerefox_get_relations shows which types exist. depth > 1 follows " + "chains (useful for follows / reply_to); cycles terminate safely. Optional " + "from_time / to_time filter neighbours by their creation time.",
+    inputSchema: {
+      type: "object",
+      required: ["document_id", "rel_type"],
+      properties: {
+        document_id: { type: "string", description: "UUID of the starting document" },
+        rel_type: { type: "string", description: "The single relation type to traverse" },
+        depth: { type: "integer", description: "How many hops to follow (1–5, default 1)" },
+        from_time: { type: "string", description: "ISO-8601: only neighbours created on/after" },
+        to_time: { type: "string", description: "ISO-8601: only neighbours created on/before" },
+        limit: { type: "integer", description: "Max documents to return (default 50, max 200)" },
+        requestor: { type: "string", description: "Name of the agent making this request" }
+      }
+    },
+    handler: getNeighborsHandler
+  };
+});
+
 // ../../_shared/mcp-tools/get-document.ts
 async function handler2(supabase, args, ctx) {
   const document_id = args.document_id;
@@ -54987,11 +55483,11 @@ var init_get_document = __esm(() => {
 });
 
 // ../../_shared/mcp-tools/get-help-content.ts
-var HELP_FULL = '# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **10 MCP tools** (9 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for "How AI Agents Use Cerefox" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token) | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project\'s docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc\'s project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., "Claude Code", "archiver"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user\'s `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don\'t write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don\'t construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you read (shown by `cerefox_get_document`, `cerefox_search`, and `cerefox_metadata_search`) when updating a document. If it\'s stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer\'s work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc\'s full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch("topic") -> find doc [id: abc123] -> get_document(abc123) -> note its content_hash -> modify ->\ningest(title="Same Title", content="...", document_id="abc123",\n       expected_content_hash="<the hash you read>", author="my-agent")\n```\n\nOn a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch("topic") -> find doc (note its hash) -> modify ->\ningest(title="Same Title", content="...", update_if_exists=true,\n       expected_content_hash="<the hash you read>", author="my-agent")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={"type": "decision-log"}, updated_since="2026-03-28T00:00:00Z")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …).\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --document-id "<uuid>" --expected-content-hash "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor "<your-name>"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor "<your-name>"` |\n| `cerefox_list_projects` | `cerefox project list --requestor "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --requestor "<your-name>"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author "<your-name>" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--requestor "<your-name>"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n', HELP_SECTIONS, HELP_SECTION_HEADINGS;
+var HELP_FULL = '# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **14 MCP tools** (13 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for "How AI Agents Use Cerefox" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token) | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_set_relation` | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project\'s docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc\'s project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., "Claude Code", "archiver"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user\'s `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don\'t write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don\'t construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you read (shown by `cerefox_get_document`, `cerefox_search`, and `cerefox_metadata_search`) when updating a document. If it\'s stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer\'s work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Relations express how documents relate; lifecycle tells you if knowledge is still good.** Use `cerefox_set_relation` when one document supersedes, contradicts, references, or continues another. `supersedes` marks the target **superseded**; `contradicts` marks **both** stale; `related_to`/`duplicates`/`contradicts` are symmetric (both directions written). Any other type string is accepted without special behaviour. When a search result or `cerefox_get_relations` shows a neighbour marked `[superseded]` or `[stale]`, say so rather than presenting it as current.\n12. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc\'s full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch("topic") -> find doc [id: abc123] -> get_document(abc123) -> note its content_hash -> modify ->\ningest(title="Same Title", content="...", document_id="abc123",\n       expected_content_hash="<the hash you read>", author="my-agent")\n```\n\nOn a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch("topic") -> find doc (note its hash) -> modify ->\ningest(title="Same Title", content="...", update_if_exists=true,\n       expected_content_hash="<the hash you read>", author="my-agent")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={"type": "decision-log"}, updated_since="2026-03-28T00:00:00Z")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …).\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --document-id "<uuid>" --expected-content-hash "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor "<your-name>"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor "<your-name>"` |\n| `cerefox_list_projects` | `cerefox project list --requestor "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_set_relation` | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --requestor "<your-name>"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author "<your-name>" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--requestor "<your-name>"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n', HELP_SECTIONS, HELP_SECTION_HEADINGS;
 var init_get_help_content = __esm(() => {
   HELP_SECTIONS = {
-    Tools: "## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token) | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |",
-    "Essential Rules": '## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., "Claude Code", "archiver"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user\'s `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don\'t write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don\'t construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you read (shown by `cerefox_get_document`, `cerefox_search`, and `cerefox_metadata_search`) when updating a document. If it\'s stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer\'s work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc\'s full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.',
+    Tools: "## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |\n| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token) | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_set_relation` | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |",
+    "Essential Rules": '## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., "Claude Code", "archiver"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user\'s `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don\'t write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don\'t construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you read (shown by `cerefox_get_document`, `cerefox_search`, and `cerefox_metadata_search`) when updating a document. If it\'s stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer\'s work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.\n10. **Search: prefer a few distinctive terms; heed `below confidence`.** When nothing clears the relevance threshold, `cerefox_search` returns the closest candidates prefixed with a `below confidence` warning instead of an empty set — that flag means **weak signal, not absent knowledge**: check the candidates\' scores and titles before concluding the KB lacks the content. A truly empty response means nothing even weakly related exists.\n11. **Relations express how documents relate; lifecycle tells you if knowledge is still good.** Use `cerefox_set_relation` when one document supersedes, contradicts, references, or continues another. `supersedes` marks the target **superseded**; `contradicts` marks **both** stale; `related_to`/`duplicates`/`contradicts` are symmetric (both directions written). Any other type string is accepted without special behaviour. When a search result or `cerefox_get_relations` shows a neighbour marked `[superseded]` or `[stale]`, say so rather than presenting it as current.\n12. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc\'s full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean "add" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.',
     "Update Workflow (ID-based -- preferred)": `## Update Workflow (ID-based -- preferred)
 
 \`\`\`
@@ -55003,7 +55499,7 @@ ingest(title="Same Title", content="...", document_id="abc123",
 On a **conflict** error: get_document again (fresh content + fresh hash) -> merge your changes -> retry with the new hash.`,
     "Update Workflow (title-based -- fallback)": '## Update Workflow (title-based -- fallback)\n\n```\nsearch("topic") -> find doc (note its hash) -> modify ->\ningest(title="Same Title", content="...", update_if_exists=true,\n       expected_content_hash="<the hash you read>", author="my-agent")\n```',
     "Catch-Up Workflow": '## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={"type": "decision-log"}, updated_since="2026-03-28T00:00:00Z")\n```',
-    "CLI fallback (when MCP is unavailable)": '## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …).\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --document-id "<uuid>" --expected-content-hash "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor "<your-name>"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor "<your-name>"` |\n| `cerefox_list_projects` | `cerefox project list --requestor "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --requestor "<your-name>"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author "<your-name>" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--requestor "<your-name>"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.'
+    "CLI fallback (when MCP is unavailable)": '## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …).\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); common flags also have single-letter short forms (`-f`, `-p`, `-c`, `-m`, `-u`, `-a`, `-r`). Use the canonical long name (what `--help` shows) or its short form — there are no long-form aliases like `--filter` or `--count`.\n\n| MCP tool | CLI |\n|---|---|\n| `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |\n| `cerefox_ingest` (paste) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf \'...\' \\| cerefox document ingest --paste --title "<t>" --document-id "<uuid>" --expected-content-hash "<hash>" --author "<your-name>" --author-type agent` |\n| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor "<your-name>"` |\n| `cerefox_list_versions` | `cerefox document version list <id> --requestor "<your-name>"` |\n| `cerefox_list_projects` | `cerefox project list --requestor "<your-name>"` |\n| `cerefox_list_metadata_keys` | `cerefox metadata keys` |\n| `cerefox_set_relation` | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |\n| `cerefox_delete_relation` | Remove a relation | `source_id`, `target_id`, `rel_type` |\n| `cerefox_get_relations` | All relations touching a document, both directions | `document_id` |\n| `cerefox_get_neighbors` | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |\n| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter \'<json>\' --requestor "<your-name>"` (list a project: `cerefox document list --project <name>`) |\n| `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author "<your-name>" --author-type agent` (or `--clear` to remove all) |\n| `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`\n- Reads: `--requestor "<your-name>"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.'
   };
   HELP_SECTION_HEADINGS = ["Tools", "Essential Rules", "Update Workflow (ID-based -- preferred)", "Update Workflow (title-based -- fallback)", "Catch-Up Workflow", "CLI fallback (when MCP is unavailable)"];
 });
@@ -55591,10 +56087,12 @@ async function handler9(supabase, args, ctx) {
   const project_name = args.project_name;
   const match_count = args.match_count ?? 5;
   const mode = args.mode ?? "docs";
-  const alpha = args.alpha ?? getSearchAlpha();
-  const min_score = args.min_score ?? getMinSearchScore();
+  const alpha = args.alpha ?? getConfiguredSearchAlpha();
+  const min_score = args.min_score ?? getConfiguredMinSearchScore();
   const min_term_coverage = args.min_term_coverage ?? getMinTermCoverage();
   const coverageParam = min_term_coverage !== undefined ? { p_min_term_coverage: min_term_coverage } : {};
+  const scoreParam = min_score !== undefined ? { p_min_score: min_score } : {};
+  const alphaParam = alpha !== undefined ? { p_alpha: alpha } : {};
   const metadata_filter = args.metadata_filter ?? null;
   const requested_max_bytes = args.max_bytes;
   const ceiling = getMaxResponseBytes();
@@ -55635,10 +56133,10 @@ async function handler9(supabase, args, ctx) {
       p_query_text: query,
       p_query_embedding: embedding,
       p_match_count: match_count,
-      p_alpha: alpha,
       p_use_upgrade: false,
       p_project_id: projectId,
-      p_min_score: min_score,
+      ...alphaParam,
+      ...scoreParam,
       ...metaFilterParam,
       ...coverageParam
     };
@@ -55648,9 +56146,9 @@ async function handler9(supabase, args, ctx) {
       p_query_text: query,
       p_query_embedding: embedding,
       p_match_count: match_count,
-      p_alpha: alpha,
       p_project_id: projectId,
-      p_min_score: min_score,
+      ...alphaParam,
+      ...scoreParam,
       ...metaFilterParam,
       ...coverageParam
     };
@@ -55816,9 +56314,22 @@ var init_set_document_projects = __esm(() => {
 });
 
 // ../../_shared/mcp-tools/index.ts
+async function listEnabledTools(supabase) {
+  const relations = await relationsEnabled(supabase);
+  return ALL_TOOLS.filter((t) => relations || !RELATION_TOOL_NAMES.has(t.name));
+}
+async function assertToolEnabled(supabase, name) {
+  if (!RELATION_TOOL_NAMES.has(name))
+    return;
+  if (await relationsEnabled(supabase))
+    return;
+  throw new McpInvalidParams(disabledToolMessage(name));
+}
 var ALL_TOOLS, TOOLS_BY_NAME;
 var init_mcp_tools = __esm(() => {
   init_audit_log();
+  init_feature_flags();
+  init_relations();
   init_get_document();
   init_get_help();
   init_ingest();
@@ -55829,6 +56340,7 @@ var init_mcp_tools = __esm(() => {
   init_search();
   init_set_document_projects();
   init_types3();
+  init_types3();
   ALL_TOOLS = [
     searchTool,
     ingestTool,
@@ -55839,6 +56351,10 @@ var init_mcp_tools = __esm(() => {
     listProjectsTool,
     setDocumentProjectsTool,
     auditLogTool,
+    setRelationTool,
+    deleteRelationTool,
+    getRelationsTool,
+    getNeighborsTool,
     getHelpTool
   ];
   TOOLS_BY_NAME = Object.fromEntries(ALL_TOOLS.map((t) => [t.name, t]));
@@ -56030,7 +56546,7 @@ __export(exports_util, {
   cleanRegex: () => cleanRegex,
   cleanEnum: () => cleanEnum,
   captureStackTrace: () => captureStackTrace,
-  cached: () => cached,
+  cached: () => cached2,
   assignProp: () => assignProp,
   assertNotEqual: () => assertNotEqual,
   assertNever: () => assertNever,
@@ -56067,7 +56583,7 @@ function jsonStringifyReplacer(_, value) {
     return value.toString();
   return value;
 }
-function cached(getter) {
+function cached2(getter) {
   const set = false;
   return {
     get value() {
@@ -56479,7 +56995,7 @@ var captureStackTrace, allowsEval, getParsedType2 = (data) => {
 }, propertyKeyTypes, primitiveTypes, NUMBER_FORMAT_RANGES, BIGINT_FORMAT_RANGES;
 var init_util2 = __esm(() => {
   captureStackTrace = Error.captureStackTrace ? Error.captureStackTrace : (..._args) => {};
-  allowsEval = cached(() => {
+  allowsEval = cached2(() => {
     if (typeof navigator !== "undefined" && navigator?.userAgent?.includes("Cloudflare")) {
       return false;
     }
@@ -57784,7 +58300,7 @@ var init_schemas = __esm(() => {
   });
   $ZodObject = /* @__PURE__ */ $constructor("$ZodObject", (inst, def) => {
     $ZodType.init(inst, def);
-    const _normalized = cached(() => {
+    const _normalized = cached2(() => {
       const keys = Object.keys(def.shape);
       for (const k of keys) {
         if (!(def.shape[k] instanceof $ZodType)) {
@@ -58004,7 +58520,7 @@ var init_schemas = __esm(() => {
       }
       return propValues;
     });
-    const disc = cached(() => {
+    const disc = cached2(() => {
       const opts = def.options;
       const map = new Map;
       for (const o of opts) {
@@ -68985,7 +69501,7 @@ function buildServer() {
   };
   const server = new Server({ name: SERVER_NAME, version: PKG_VERSION }, { capabilities: { tools: {} } });
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: ALL_TOOLS.map((t) => ({
+    tools: (await listEnabledTools(supabase)).map((t) => ({
       name: t.name,
       description: t.description,
       inputSchema: t.inputSchema
@@ -68998,6 +69514,7 @@ function buildServer() {
       throw new McpInvalidParams(`Unknown tool: ${name}`);
     }
     try {
+      await assertToolEnabled(supabase, name);
       const text = await tool.handler(supabase, args, ctx);
       return { content: [{ type: "text", text }] };
     } catch (err) {
@@ -69053,7 +69570,7 @@ var init_server3 = __esm(() => {
 // src/bin/cerefox.ts
 init_cli_core();
 
-// ../../node_modules/.bun/commander@12.1.0/node_modules/commander/esm.mjs
+// ../../node_modules/.bun/commander@14.0.3/node_modules/commander/esm.mjs
 var import__ = __toESM(require_commander(), 1);
 var {
   program,
@@ -69118,7 +69635,13 @@ function utcStamp() {
   return d.getUTCFullYear().toString() + pad(d.getUTCMonth() + 1) + pad(d.getUTCDate()) + "T" + pad(d.getUTCHours()) + pad(d.getUTCMinutes()) + pad(d.getUTCSeconds()) + "Z";
 }
 async function action(options) {
-  const outDir = resolve(expandHome(options.outputDir ?? process.env.CEREFOX_BACKUP_DIR ?? "~/.cerefox/backups"));
+  const configuredDir = options.outputDir ?? process.env.CEREFOX_BACKUP_DIR;
+  const outDir = resolve(expandHome(configuredDir ?? "~/.cerefox/backups"));
+  if (configuredDir !== undefined && !configuredDir.startsWith("/") && !configuredDir.startsWith("~")) {
+    println(c.yellow("⚠ ") + `Backup directory "${configuredDir}" is relative — it resolves against the ` + "current working directory, so backups land in different places depending " + "on where you run this from.");
+    println(c.dim(`  Writing to: ${outDir}`));
+    println(c.dim("  Set an absolute path (e.g. ~/.cerefox/backups) to keep them together."));
+  }
   if (!existsSync2(outDir))
     mkdirSync(outDir, { recursive: true });
   const stamp = utcStamp();
@@ -69129,12 +69652,30 @@ async function action(options) {
   try {
     schemaVersion = await client.rpc("cerefox_schema_version", {}) ?? "unknown";
   } catch {}
+  const includeTrash = options.trash !== false;
+  const BASE_COLUMNS = "id, title, content_hash, source, metadata, total_chars, chunk_count, " + "review_status, created_at, updated_at, deleted_at";
+  const fetchDocs = (columns) => fetchAllPages((from, to) => {
+    const q = client.raw.from("cerefox_documents").select(columns);
+    return (includeTrash ? q : q.is("deleted_at", null)).order("created_at", { ascending: true }).order("id", { ascending: true }).range(from, to);
+  });
   let docs;
+  let lifecycleCaptured = true;
   try {
-    docs = await fetchAllPages((from, to) => client.raw.from("cerefox_documents").select("id, title, content_hash, source, metadata, total_chars, chunk_count, " + "review_status, created_at, updated_at, deleted_at").is("deleted_at", null).order("created_at", { ascending: true }).order("id", { ascending: true }).range(from, to));
+    docs = await fetchDocs(`${BASE_COLUMNS}, lifecycle_status`);
   } catch (err) {
-    throw systemError(`Document fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+    const message = err instanceof Error ? err.message : String(err);
+    if (!/lifecycle_status/.test(message)) {
+      throw systemError(`Document fetch failed: ${message}`);
+    }
+    lifecycleCaptured = false;
+    try {
+      docs = await fetchDocs(BASE_COLUMNS);
+    } catch (retryErr) {
+      throw systemError(`Document fetch failed: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
+    }
+    println(c.dim("  (server predates lifecycle_status — captured without it)"));
   }
+  const trashedCount = docs.filter((d) => d.deleted_at != null).length;
   let projects = [];
   let memberships = [];
   try {
@@ -69143,6 +69684,19 @@ async function action(options) {
   } catch (err) {
     throw systemError(`Project/membership fetch failed: ${err instanceof Error ? err.message : String(err)}`);
   }
+  let relations = [];
+  try {
+    relations = await fetchAllPages((from, to) => client.raw.from("cerefox_document_relations").select("source_id, target_id, rel_type, metadata, author, author_type, created_at").order("source_id", { ascending: true }).order("target_id", { ascending: true }).order("rel_type", { ascending: true }).range(from, to));
+  } catch {}
+  {
+    const captured = new Set(docs.map((d) => d.id));
+    const before = memberships.length;
+    memberships = memberships.filter((m) => captured.has(m.document_id));
+    const dropped = before - memberships.length;
+    if (dropped > 0) {
+      println(c.dim(`  (skipped ${dropped} membership(s) belonging to trashed documents)`));
+    }
+  }
   let chunkTotal = 0;
   const enriched = [];
   for (let i = 0;i < docs.length; i++) {
@@ -69166,27 +69720,37 @@ async function action(options) {
   const payload = {
     created_at: new Date().toISOString(),
     cerefox_version: PKG_VERSION,
-    backup_format: 2,
+    backup_format: 4,
     schema_version: schemaVersion,
     document_count: docs.length,
+    trashed_count: trashedCount,
+    includes_trash: includeTrash,
+    includes_lifecycle_status: lifecycleCaptured,
     chunk_count: chunkTotal,
     project_count: projects.length,
     membership_count: memberships.length,
+    relation_count: relations.length,
     projects,
     memberships,
+    relations,
     documents: enriched
   };
   writeFileSync(dest, JSON.stringify(payload, null, 2), "utf8");
   println("");
   println(c.green("✓ ") + `Backup written: ${dest}`);
-  println(c.dim(`  documents: ${docs.length} · chunks: ${chunkTotal} · ` + `projects: ${projects.length} · memberships: ${memberships.length}`));
+  println(c.dim(`  documents: ${docs.length} · chunks: ${chunkTotal} · ` + `projects: ${projects.length} · memberships: ${memberships.length}` + (relations.length > 0 ? ` · relations: ${relations.length}` : "")));
+  if (!includeTrash) {
+    println(c.dim("  trashed documents: excluded (--no-trash)"));
+  } else if (trashedCount > 0) {
+    println(c.dim(`  of which trashed: ${trashedCount} (restored as trash, not resurrected)`));
+  }
   if (options.git) {
     println(c.yellow("⚠ ") + "--git commit is not implemented; the snapshot was written without a git checkpoint.");
     println(c.dim("  Commit the backup directory yourself if you want it version-controlled."));
   }
 }
 function registerBackup(program2) {
-  program2.command("backup").description("Write a JSON snapshot of the knowledge base.").option("-o, --output-dir <dir>", "Snapshot output directory (default: CEREFOX_BACKUP_DIR or ~/.cerefox/backups).").option("-l, --label <label>", "Optional suffix added to the filename.").option("--include-versions", "Include archived versions in the snapshot. (v0.5: ignored — current chunks only.)").option("--git", "Commit the snapshot to the output dir as a git checkpoint. (v0.5: ignored.)").action(action);
+  program2.command("backup").description("Write a JSON snapshot of the knowledge base.").option("-o, --output-dir <dir>", "Snapshot output directory (default: CEREFOX_BACKUP_DIR or ~/.cerefox/backups).").option("-l, --label <label>", "Optional suffix added to the filename.").option("--include-versions", "Include archived versions in the snapshot. (v0.5: ignored — current chunks only.)").option("--git", "Commit the snapshot to the output dir as a git checkpoint. (v0.5: ignored.)").option("--no-trash", "Exclude soft-deleted documents. Default: they are captured and restored as trash.").action(action);
 }
 
 // src/cli/commands/completion.ts
@@ -69497,6 +70061,22 @@ var CONFIG_KEYS = [
   {
     key: "requestor_identity_format",
     description: "Regex the requestor/author must match (only enforced when the above is on)."
+  },
+  {
+    key: "min_search_score",
+    description: "0–1 — minimum cosine similarity for vector-side results. Default 0.5 (use 0.6 with the local embedder)."
+  },
+  {
+    key: "min_term_coverage",
+    description: "0–1 — fraction of a query's meaningful terms a keyword OR-fallback match must cover to count as confident. Default 0.5."
+  },
+  {
+    key: "relations_enabled",
+    description: "'true'/'false' — expose the document-relation tools to agents. Off by default; the feature is dormant until enabled (iteration 29)."
+  },
+  {
+    key: "search_alpha",
+    description: "0–1 — hybrid fusion weight: 1 = pure semantic, 0 = pure keyword. Default 0.7."
   }
 ];
 function action4(options) {
@@ -75039,8 +75619,8 @@ import { homedir as homedir6 } from "node:os";
 import { join as join9 } from "node:path";
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "1.0.8";
-var EF_LAST_CHANGED = "1.0.6";
+var EF_VERSION = "1.1.0-beta.2";
+var EF_LAST_CHANGED = "1.1.0-beta.2";
 
 // src/cli/util/checks.ts
 init_config();
@@ -75389,7 +75969,7 @@ async function checkContentFormat() {
       name: CONTENT_FORMAT_CHECK_NAME,
       status: "skipped",
       detail: `${legacy} of ${total} document(s) use the legacy reconstruction format (format 1).`,
-      hint: "They auto-convert on next edit; run `cerefox server migrate-format` to convert all now (re-embeds; `--dry-run` first). What this means: `cerefox guides show content-format`."
+      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) {
     return {
@@ -75687,11 +76267,17 @@ async function action15(options) {
     process.exit(1);
   }
   if (!options.json) {
-    println(cErr.green("✓") + ` All checks passed${warnCount > 0 ? ` (${warnCount} warning${warnCount === 1 ? "" : "s"})` : ""}.`);
+    if (warnCount > 0) {
+      println(cErr.yellow("⚠ ") + `${warnCount} warning${warnCount === 1 ? "" : "s"} — see above.`);
+    } else {
+      println(cErr.green("✓") + " All checks passed.");
+    }
   }
+  if (options.strict && warnCount > 0)
+    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).").action(action15);
+  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(action15);
 }
 
 // src/cli/commands/get-audit-log.ts
@@ -75738,6 +76324,134 @@ 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(action16);
 }
 
+// src/cli/commands/relation.ts
+init_cli_core();
+init_client();
+var UUID_RE3 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function requireUuid(value, field) {
+  const v = value.trim();
+  if (!UUID_RE3.test(v)) {
+    throw userError(`${field} must be a document UUID (got: ${value}).`, "Search for the document first — results show `[id: <uuid>]`.");
+  }
+  return v;
+}
+function registerRelationSet(program2) {
+  program2.command("set <source-id> <rel-type> <target-id>").description("Link two documents: <source> --<rel-type>--> <target>.").option("--meta <json>", "JSON metadata for the edge (note, confidence, …).").option("--author <name>", "Who is creating this relation.").option("--json", "Emit machine-readable JSON.").action(async (sourceId, relType, targetId, options) => {
+    const source = requireUuid(sourceId, "source-id");
+    const target = requireUuid(targetId, "target-id");
+    if (!relType.trim())
+      throw userError("rel-type is required.");
+    let metadata = {};
+    if (options.meta) {
+      try {
+        metadata = JSON.parse(options.meta);
+      } catch {
+        throw userError(`--meta must be valid JSON (got: ${options.meta})`);
+      }
+    }
+    const author = resolveAuthor(options.author);
+    const authorType = resolveAuthorType(undefined);
+    if (author === "unknown") {
+      warn("No --author / CEREFOX_AUTHOR_NAME set — audit log will record this write as 'unknown'.");
+    }
+    const client = getClient();
+    const data = await client.rpc("cerefox_set_relation", {
+      p_source_id: source,
+      p_target_id: target,
+      p_rel_type: relType.trim(),
+      p_author: author,
+      p_author_type: authorType,
+      p_metadata: metadata
+    });
+    const symmetric = Boolean(data?.[0]?.is_symmetric);
+    if (options.json) {
+      printJson({ source, target, rel_type: relType.trim(), symmetric });
+      return;
+    }
+    println(c.green("✓ ") + `${source} --${relType.trim()}--> ${target}` + (symmetric ? c.dim(" (symmetric — reverse edge written too)") : ""));
+    if (relType.trim() === "supersedes")
+      println(c.dim("  Target marked superseded."));
+    if (relType.trim() === "contradicts")
+      println(c.dim("  Both documents marked stale."));
+  });
+}
+function registerRelationDelete(program2) {
+  program2.command("delete <source-id> <rel-type> <target-id>").description("Remove a relation (symmetric types remove both directions).").option("--author <name>", "Who is removing this relation.").action(async (sourceId, relType, targetId, options) => {
+    const source = requireUuid(sourceId, "source-id");
+    const target = requireUuid(targetId, "target-id");
+    const author = resolveAuthor(options.author);
+    const authorType = resolveAuthorType(undefined);
+    if (author === "unknown") {
+      warn("No --author / CEREFOX_AUTHOR_NAME set — audit log will record this write as 'unknown'.");
+    }
+    const client = getClient();
+    const removed = await client.rpc("cerefox_delete_relation", {
+      p_source_id: source,
+      p_target_id: target,
+      p_rel_type: relType.trim(),
+      p_author: author,
+      p_author_type: authorType
+    });
+    if (!removed) {
+      println(c.dim("(no such relation — nothing removed)"));
+      return;
+    }
+    println(c.green("✓ ") + `Removed ${removed} relation row(s).`);
+    println(c.dim("  Lifecycle status left as-is — a document may be superseded by something else."));
+  });
+}
+function registerRelationList(program2) {
+  program2.command("list <document-id>").description("Show every relation touching a document (both directions).").option("--json", "Emit machine-readable JSON.").action(async (documentId, options) => {
+    const id = requireUuid(documentId, "document-id");
+    const client = getClient();
+    const rows = await client.rpc("cerefox_get_relations", {
+      p_document_id: id
+    }) ?? [];
+    if (options.json) {
+      printJson(rows);
+      return;
+    }
+    if (rows.length === 0) {
+      println(c.dim("(no relations)"));
+      return;
+    }
+    for (const r of rows) {
+      const arrow = r.direction === "outbound" ? "→" : "←";
+      const life = r.other_lifecycle && r.other_lifecycle !== "active" ? c.yellow(` [${r.other_lifecycle}]`) : "";
+      println(`  ${arrow} ${c.bold(r.rel_type)}  ${r.other_title}${life} ${c.dim(`[id: ${r.other_id}]`)}`);
+    }
+  });
+}
+function registerRelationNeighbors(program2) {
+  program2.command("neighbors <document-id> <rel-type>").description("Walk the graph from a document along one relation type.").option("-d, --depth <n>", "Hops to follow (1–5).", "1").option("-l, --limit <n>", "Max documents to return.", "50").option("--json", "Emit machine-readable JSON.").action(async (documentId, relType, options) => {
+    const id = requireUuid(documentId, "document-id");
+    const depth = Number.parseInt(options.depth ?? "1", 10);
+    const limit = Number.parseInt(options.limit ?? "50", 10);
+    if (Number.isNaN(depth) || depth < 1 || depth > 5) {
+      throw userError("--depth must be between 1 and 5.");
+    }
+    const client = getClient();
+    const rows = await client.rpc("cerefox_get_neighbors", {
+      p_document_id: id,
+      p_rel_type: relType.trim(),
+      p_depth: depth,
+      p_limit: Number.isNaN(limit) ? 50 : limit
+    }) ?? [];
+    if (options.json) {
+      printJson(rows);
+      return;
+    }
+    if (rows.length === 0) {
+      println(c.dim(`(nothing reachable via "${relType.trim()}")`));
+      return;
+    }
+    for (const r of rows) {
+      const life = r.lifecycle_status && r.lifecycle_status !== "active" ? c.yellow(` [${r.lifecycle_status}]`) : "";
+      println(`  ${c.dim(`depth ${r.depth}`)} ${r.direction === "outbound" ? "→" : "←"} ` + `${r.title}${life} ${c.dim(`[id: ${r.document_id}]`)}`);
+    }
+  });
+}
+
 // src/cli/commands/get-doc.ts
 init_cli_core();
 init_cli_core();
@@ -77554,6 +78268,10 @@ async function action29(target, options) {
   } else {
     warn("This backup predates project-membership capture (format 1) — documents " + "will be restored WITHOUT their project assignments.");
   }
+  const trashedInFile = payload.documents.filter((d) => d.deleted_at != null).length;
+  if (trashedInFile > 0) {
+    println(c.dim(`  trashed documents in file: ${trashedInFile} — restored as trash ` + "(still deleted; recover with `cerefox document restore`)"));
+  }
   println("");
   const client = getClient();
   let restored = 0;
@@ -77561,7 +78279,7 @@ async function action29(target, options) {
   let errors4 = 0;
   const errorDetails = [];
   for (const doc2 of payload.documents) {
-    const { data: existing } = await client.raw.from("cerefox_documents").select("id").eq("content_hash", doc2.content_hash).maybeSingle();
+    const { data: existing } = await client.raw.from("cerefox_documents").select("id").or(`id.eq.${doc2.id},content_hash.eq.${doc2.content_hash}`).limit(1).maybeSingle();
     if (existing) {
       skipped++;
       continue;
@@ -77590,6 +78308,7 @@ async function action29(target, options) {
   }
   let projectsRestored = 0;
   let membershipsRestored = 0;
+  let relationsRestored = 0;
   if (!options.dryRun && hasMemberships) {
     const projects = payload.projects ?? [];
     if (projects.length > 0) {
@@ -77623,11 +78342,33 @@ async function action29(target, options) {
       }
       membershipsRestored += links.slice(i, i + 500).length;
     }
+    const relations = (payload.relations ?? []).filter((r) => presentDocIds.has(r.source_id) && presentDocIds.has(r.target_id));
+    if (relations.length > 0) {
+      for (let i = 0;i < relations.length; i += 500) {
+        const { error: relErr } = await client.raw.from("cerefox_document_relations").upsert(relations.slice(i, i + 500), {
+          onConflict: "source_id,target_id,rel_type",
+          ignoreDuplicates: true
+        });
+        if (relErr) {
+          errorDetails.push({ title: "(relations)", error: relErr.message });
+          errors4++;
+          break;
+        }
+        relationsRestored += relations.slice(i, i + 500).length;
+      }
+      const dropped = (payload.relations?.length ?? 0) - relations.length;
+      if (dropped > 0) {
+        warn(`${dropped} relation(s) skipped — one or both documents were not restored.`);
+      }
+    }
   }
   println("");
   println((options.dryRun ? c.yellow("(dry-run) ") : "") + c.bold(`Summary: ${restored} restored · ${skipped} skipped · ${errors4} errors`));
   if (hasMemberships && !options.dryRun) {
-    println(c.dim(`  projects: ${projectsRestored} · memberships: ${membershipsRestored}`));
+    println(c.dim(`  projects: ${projectsRestored} · memberships: ${membershipsRestored}` + (relationsRestored > 0 ? ` · relations: ${relationsRestored}` : "")));
+  }
+  if (trashedInFile > 0) {
+    println(c.dim(`  ${trashedInFile} of those are trashed and stay trashed.`));
   }
   if (errors4 > 0) {
     println("");
@@ -77666,8 +78407,10 @@ async function action30(query, options) {
     throw userError("Empty query.");
   }
   const matchCount = parsePositiveInt(options.matchCount, "--match-count", 5);
-  const alpha = parseFloat01(options.alpha, "--alpha", getSearchAlpha());
-  const minScore = parseFloat01(options.minScore, "--min-score", getMinSearchScore());
+  const envAlpha = getConfiguredSearchAlpha();
+  const alphaParam = options.alpha !== undefined ? { p_alpha: parseFloat01(options.alpha, "--alpha", envAlpha ?? 0.7) } : envAlpha !== undefined ? { p_alpha: envAlpha } : {};
+  const envScore = getConfiguredMinSearchScore();
+  const scoreParam = options.minScore !== undefined ? { p_min_score: parseFloat01(options.minScore, "--min-score", envScore ?? 0.5) } : envScore !== undefined ? { p_min_score: envScore } : {};
   const envCoverage = getMinTermCoverage();
   const coverageParam = options.minTermCoverage !== undefined ? { p_min_term_coverage: parseFloat01(options.minTermCoverage, "--min-term-coverage", envCoverage ?? 0.5) } : envCoverage !== undefined ? { p_min_term_coverage: envCoverage } : {};
   const maxBytes = parseNonNegativeInt(options.maxBytes, "--max-bytes", getMaxResponseBytes());
@@ -77709,10 +78452,10 @@ async function action30(query, options) {
       p_query_text: query,
       p_query_embedding: embedding,
       p_match_count: matchCount,
-      p_alpha: alpha,
       p_use_upgrade: false,
       p_project_id: projectId,
-      p_min_score: minScore,
+      ...alphaParam,
+      ...scoreParam,
       ...metaFilterParam,
       ...coverageParam
     };
@@ -77722,9 +78465,9 @@ async function action30(query, options) {
       p_query_text: query,
       p_query_embedding: embedding,
       p_match_count: matchCount,
-      p_alpha: alpha,
       p_project_id: projectId,
-      p_min_score: minScore,
+      ...alphaParam,
+      ...scoreParam,
       ...metaFilterParam,
       ...coverageParam
     };
@@ -77908,7 +78651,8 @@ async function action31(options) {
     stdio: "inherit"
   });
   if (result.status !== 0) {
-    throw systemError(`${runtime.description} install failed (exit ${result.status}).`, `Try the manual command: \`${runtime.command} ${runtime.args(target).join(" ")}\``);
+    const notFound2 = result.error?.code === "ENOENT";
+    throw systemError(notFound2 ? `${runtime.description} was not found on PATH (tried \`${runtime.command}\`).` : `${runtime.description} install failed (exit ${result.status}).`, notFound2 ? `Install ${runtime.description}, or upgrade manually: \`${runtime.command} ${runtime.args(target).join(" ")}\`` : `Try the manual command: \`${runtime.command} ${runtime.args(target).join(" ")}\``);
   }
   println("");
   println(c.green(`✓ Upgraded to ${target}.`));
@@ -81626,7 +82370,7 @@ function logWebUsage(ctx, params) {
 }
 
 // src/web/routes/discovery.ts
-var UUID_RE3 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var UUID_RE4 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var DOC_COLS = "id, title, source, source_path, content_hash, metadata, chunk_count, total_chars, review_status, created_at, updated_at, deleted_at";
 function jsonByteLength(value) {
   return Buffer.byteLength(JSON.stringify(value), "utf8");
@@ -82098,7 +82842,7 @@ function registerDiscoveryRoutes(app, ctx) {
     if (!path) {
       return c2.json({ tried_path: "", anchor, matches: [] });
     }
-    if (UUID_RE3.test(path)) {
+    if (UUID_RE4.test(path)) {
       if (path === fromDocId) {
         return c2.json({ tried_path: path, anchor, matches: [] });
       }
@@ -83260,7 +84004,13 @@ import {
 } from "node:fs";
 import { homedir as homedir9 } from "node:os";
 import { join as join18 } from "node:path";
-var STATE_DIR = join18(homedir9(), ".cerefox");
+function resolveStateDir(override = process.env.CEREFOX_CONFIG_DIR, home = homedir9()) {
+  override = (override ?? "").trim();
+  if (!override)
+    return join18(home, ".cerefox");
+  return override === "~" || override.startsWith("~/") ? join18(home, override.slice(2)) : override;
+}
+var STATE_DIR = resolveStateDir();
 var PID_FILE = join18(STATE_DIR, "web.pid");
 var LOG_FILE = join18(STATE_DIR, "web.log");
 var daemonPaths = { stateDir: STATE_DIR, pidFile: PID_FILE, logFile: LOG_FILE };
@@ -83607,6 +84357,11 @@ Learn more:
   const metadata = program2.command("metadata").description("Metadata: keys, search.");
   moveInto(metadata, registerListMetadataKeys, "keys");
   moveInto(metadata, registerMetadataSearch, "search");
+  const relation = program2.command("relation").description("Document relations: set, delete, list, neighbors.");
+  registerRelationSet(relation);
+  registerRelationDelete(relation);
+  registerRelationList(relation);
+  registerRelationNeighbors(relation);
   const audit = program2.command("audit").description("Audit log: list.");
   moveInto(audit, registerGetAuditLog, "list");
   const config2 = program2.command("config").description("Runtime config: list, get, set.");