facult 2.5.1 → 2.6.0

package/README.md

@@ -445,6 +445,7 @@ The canonical store can contain several distinct asset classes:
 - `skills/`: workflow-specific capability folders
 - `mcp/`: canonical MCP server definitions
 - `tools/<tool>/config.toml`: canonical tool config
+- `tools/<tool>/config.local.toml`: machine-local tool config overlay
 - `tools/<tool>/rules/*.rules`: canonical tool rules
 - global docs such as `AGENTS.global.md` and `AGENTS.override.global.md`
 
@@ -479,6 +480,8 @@ Built-ins currently include:
 Recommended split:
 - `~/.ai/config.toml` or `<repo>/.ai/config.toml`: tracked, portable, non-secret refs/defaults
 - `~/.ai/config.local.toml` or `<repo>/.ai/config.local.toml`: ignored, machine-local paths and secrets
+- `~/.ai/tools/<tool>/config.toml` or `<repo>/.ai/tools/<tool>/config.toml`: tracked tool defaults
+- `~/.ai/tools/<tool>/config.local.toml` or `<repo>/.ai/tools/<tool>/config.local.toml`: ignored, machine-local tool overrides merged after tracked tool config during sync
 - `[builtin].sync_defaults = false`: disable builtin default sync/materialization for this root
 - `fclt sync --builtin-conflicts overwrite`: allow packaged builtin defaults to overwrite locally modified generated targets
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Manage canonical AI capabilities, sync surfaces, and evolution state.",
   "type": "module",
   "license": "MIT",

package/src/global-docs.ts

@@ -426,7 +426,16 @@ export async function planToolConfigSync(args: {
   previouslyManaged?: boolean;
 }): Promise<ToolConfigPlan> {
   const sourcePath = join(args.rootDir, "tools", args.tool, "config.toml");
-  if (!(await fileExists(sourcePath))) {
+  const localSourcePath = join(
+    args.rootDir,
+    "tools",
+    args.tool,
+    "config.local.toml"
+  );
+  const hasTrackedSource = await fileExists(sourcePath);
+  const hasLocalSource = await fileExists(localSourcePath);
+
+  if (!(hasTrackedSource || hasLocalSource)) {
     return {
       targetPath: args.toolConfigPath,
       write: false,
@@ -437,14 +446,28 @@ export async function planToolConfigSync(args: {
     };
   }
 
-  const rendered = await renderSourceTarget({
-    homeDir: args.homeDir,
-    rootDir: args.rootDir,
-    sourcePath,
-    targetPath: args.toolConfigPath,
-    tool: args.tool,
-  });
-  const canonicalConfig = Bun.TOML.parse(rendered);
+  const trackedRendered = hasTrackedSource
+    ? await renderSourceTarget({
+        homeDir: args.homeDir,
+        rootDir: args.rootDir,
+        sourcePath,
+        targetPath: args.toolConfigPath,
+        tool: args.tool,
+      })
+    : null;
+  const localRendered = hasLocalSource
+    ? await renderSourceTarget({
+        homeDir: args.homeDir,
+        rootDir: args.rootDir,
+        sourcePath: localSourcePath,
+        targetPath: args.toolConfigPath,
+        tool: args.tool,
+      })
+    : null;
+  const canonicalConfig = trackedRendered
+    ? Bun.TOML.parse(trackedRendered)
+    : {};
+  const localConfig = localRendered ? Bun.TOML.parse(localRendered) : {};
   const existingConfig =
     (await readTomlFile(args.toolConfigPath)) ??
     (args.existingConfigPath
@@ -452,8 +475,11 @@ export async function planToolConfigSync(args: {
       : null) ??
     ({} as Record<string, unknown>);
   const merged = mergeTomlObjects(
-    existingConfig,
-    isPlainObject(canonicalConfig) ? canonicalConfig : {}
+    mergeTomlObjects(
+      existingConfig,
+      isPlainObject(canonicalConfig) ? canonicalConfig : {}
+    ),
+    isPlainObject(localConfig) ? localConfig : {}
   );
   const nextContents = stringifyTomlObject(merged);
   const current = await readTextIfExists(args.toolConfigPath);
@@ -462,7 +488,7 @@ export async function planToolConfigSync(args: {
     write: current !== `${nextContents}\n`,
     remove: false,
     contents: nextContents,
-    sourcePath,
+    sourcePath: hasLocalSource ? localSourcePath : sourcePath,
     managedConfig: true,
   };
 }

package/src/manage.ts

@@ -586,15 +586,34 @@ async function loadCanonicalAutomations(
   return await loadAutomationEntries(join(rootDir, "automations"));
 }
 
+function isAutomationRuntimeRelativePath(relPath: string): boolean {
+  return relPath === "memory.md";
+}
+
+function isAutomationRuntimeTargetPath(targetPath: string): boolean {
+  return basename(targetPath) === "memory.md";
+}
+
 function automationEntriesEqual(
   left: AutomationEntry,
   right: AutomationEntry
 ): boolean {
-  if (left.files.size !== right.files.size) {
+  const leftFiles = new Map(
+    [...left.files.entries()].filter(
+      ([relPath]) => !isAutomationRuntimeRelativePath(relPath)
+    )
+  );
+  const rightFiles = new Map(
+    [...right.files.entries()].filter(
+      ([relPath]) => !isAutomationRuntimeRelativePath(relPath)
+    )
+  );
+
+  if (leftFiles.size !== rightFiles.size) {
     return false;
   }
-  for (const [relPath, leftRaw] of left.files.entries()) {
-    if (right.files.get(relPath) !== leftRaw) {
+  for (const [relPath, leftRaw] of leftFiles.entries()) {
+    if (rightFiles.get(relPath) !== leftRaw) {
       return false;
     }
   }
@@ -816,23 +835,27 @@ async function planAutomationFileChanges(args: {
   const contents = new Map<string, string>();
   const sources = new Map<string, string>();
   const desiredPaths = new Set<string>();
+  const add = new Set<string>();
 
   for (const automation of automations) {
     for (const [relPath, raw] of automation.files.entries()) {
       const targetPath = join(args.automationDir, automation.name, relPath);
       const sourcePath = join(automation.sourceDir, relPath);
-      desiredPaths.add(targetPath);
       contents.set(targetPath, raw);
-      sources.set(targetPath, sourcePath);
-    }
-  }
 
-  const add = new Set<string>();
-  for (const targetPath of desiredPaths) {
-    const current = await readTextIfExists(targetPath);
-    const desired = contents.get(targetPath);
-    if (desired != null && current !== desired) {
-      add.add(targetPath);
+      if (isAutomationRuntimeRelativePath(relPath)) {
+        if ((await readTextIfExists(targetPath)) == null) {
+          add.add(targetPath);
+        }
+        continue;
+      }
+
+      desiredPaths.add(targetPath);
+      sources.set(targetPath, sourcePath);
+      const current = await readTextIfExists(targetPath);
+      if (current !== raw) {
+        add.add(targetPath);
+      }
     }
   }
 
@@ -841,6 +864,7 @@ async function planAutomationFileChanges(args: {
       (args.previouslyManagedTargets ?? []).filter(
         (targetPath) =>
           targetPath.startsWith(join(args.automationDir, "")) &&
+          !isAutomationRuntimeTargetPath(targetPath) &&
           !desiredPaths.has(targetPath)
       )
     )
@@ -2973,6 +2997,30 @@ function updateRenderedTargetState(args: {
   args.entry.renderedTargets = next;
 }
 
+function pruneAutomationRuntimeRenderedTargets(args: {
+  entry: ManagedToolState;
+  automationDir?: string;
+}) {
+  if (!(args.automationDir && args.entry.renderedTargets)) {
+    return;
+  }
+  const prefix = join(args.automationDir, "");
+  const next = { ...args.entry.renderedTargets };
+  let changed = false;
+  for (const targetPath of Object.keys(next)) {
+    if (
+      targetPath.startsWith(prefix) &&
+      isAutomationRuntimeTargetPath(targetPath)
+    ) {
+      delete next[targetPath];
+      changed = true;
+    }
+  }
+  if (changed) {
+    args.entry.renderedTargets = next;
+  }
+}
+
 function logSyncDryRun({
   tool,
   entry,
@@ -3177,6 +3225,11 @@ async function syncManagedToolEntry({
   dryRun?: boolean;
   builtinConflictMode?: "warn" | "overwrite";
 }) {
+  pruneAutomationRuntimeRenderedTargets({
+    entry,
+    automationDir: entry.automationDir,
+  });
+
   const adoptedSkills = dryRun
     ? []
     : await repairManagedCanonicalContent({