facult 2.5.2 → 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.2",
+  "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,
   };
 }