facult 1.1.0 → 1.2.0

package/src/audit/update-index.ts

@@ -17,6 +17,7 @@ function ensureIndexStructure(index: FacultIndex): FacultIndex {
     mcp: index.mcp ?? { servers: {} },
     agents: index.agents ?? {},
     snippets: index.snippets ?? {},
+    instructions: index.instructions ?? {},
   };
 }
 

package/src/autosync.ts

@@ -2,8 +2,9 @@ import { watch as fsWatch } from "node:fs";
 import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, hostname } from "node:os";
 import { basename, dirname, join } from "node:path";
+import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
 import { syncManagedTools } from "./manage";
-import { facultRootDir, facultStateDir } from "./paths";
+import { facultRootDir, facultStateDir, projectRootFromAiRoot } from "./paths";
 
 const AUTOSYNC_VERSION = 1 as const;
 const DEFAULT_DEBOUNCE_MS = 1500;
@@ -109,8 +110,30 @@ function autosyncLogsDir(home: string): string {
   return join(autosyncDir(home), "logs");
 }
 
-function autosyncServiceName(tool?: string): string {
-  return tool?.trim() ? tool.trim() : "all";
+function serviceSuffix(
+  rootDir: string | undefined,
+  home: string
+): string | null {
+  if (!rootDir) {
+    return null;
+  }
+  const projectRoot = projectRootFromAiRoot(rootDir, home);
+  if (!projectRoot) {
+    return null;
+  }
+  const base = basename(projectRoot).trim().toLowerCase();
+  const slug = base.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || "project";
+}
+
+function autosyncServiceName(
+  tool?: string,
+  rootDir?: string,
+  home: string = homedir()
+): string {
+  const base = tool?.trim() ? tool.trim() : "all";
+  const suffix = serviceSuffix(rootDir, home);
+  return suffix ? `${base}-${suffix}` : base;
 }
 
 function autosyncLabel(serviceName: string): string {
@@ -318,6 +341,7 @@ function defaultAutosyncConfig(args: {
   serviceName: string;
   tool?: string;
   homeDir: string;
+  rootDir?: string;
   remote?: string;
   branch?: string;
   intervalMinutes?: number;
@@ -328,7 +352,7 @@ function defaultAutosyncConfig(args: {
     version: AUTOSYNC_VERSION,
     name: args.serviceName,
     tool: args.tool,
-    rootDir: facultRootDir(args.homeDir),
+    rootDir: args.rootDir ?? facultRootDir(args.homeDir),
     debounceMs: DEFAULT_DEBOUNCE_MS,
     git: {
       enabled: args.gitEnabled ?? true,
@@ -715,6 +739,9 @@ Options:
   --git-branch <name>           Git branch for canonical repo sync (default: main)
   --git-interval-minutes <n>    Remote git sync interval in minutes (default: 60)
   --git-disable                 Disable remote git sync for this service
+  --root <path>                 Select a canonical .ai root explicitly
+  --global                      Force the global canonical root
+  --project                     Force the nearest repo-local .ai root
   --once                        Run one local+remote sync cycle and exit
 `;
 }
@@ -722,17 +749,22 @@ Options:
 export async function installAutosyncService(args: {
   tool?: string;
   homeDir?: string;
+  rootDir?: string;
   gitRemote?: string;
   gitBranch?: string;
   gitIntervalMinutes?: number;
   gitEnabled?: boolean;
 }): Promise<AutosyncServiceConfig> {
   const home = args.homeDir ?? homedir();
-  const serviceName = autosyncServiceName(args.tool);
+  const rootDir =
+    args.rootDir ??
+    resolveCliContextRoot({ homeDir: home, cwd: process.cwd() });
+  const serviceName = autosyncServiceName(args.tool, rootDir, home);
   const config = defaultAutosyncConfig({
     serviceName,
     tool: args.tool,
     homeDir: home,
+    rootDir,
     remote: args.gitRemote,
     branch: args.gitBranch,
     intervalMinutes: args.gitIntervalMinutes,
@@ -760,9 +792,13 @@ export async function installAutosyncService(args: {
 export async function uninstallAutosyncService(args: {
   tool?: string;
   homeDir?: string;
+  rootDir?: string;
 }): Promise<void> {
   const home = args.homeDir ?? homedir();
-  const serviceName = autosyncServiceName(args.tool);
+  const rootDir =
+    args.rootDir ??
+    resolveCliContextRoot({ homeDir: home, cwd: process.cwd() });
+  const serviceName = autosyncServiceName(args.tool, rootDir, home);
   const label = autosyncLabel(serviceName);
   const domain = launchdDomain();
 
@@ -787,7 +823,9 @@ export async function repairAutosyncServices(
     if (!config) {
       continue;
     }
-    const desiredRoot = facultRootDir(homeDir);
+    const desiredRoot = projectRootFromAiRoot(config.rootDir, homeDir)
+      ? config.rootDir
+      : facultRootDir(homeDir);
     if (config.rootDir !== desiredRoot) {
       config.rootDir = desiredRoot;
       await saveAutosyncConfig(config, homeDir);
@@ -827,9 +865,13 @@ export async function repairAutosyncServices(
 export async function autosyncStatus(args: {
   tool?: string;
   homeDir?: string;
+  rootDir?: string;
 }): Promise<AutosyncStatus> {
   const home = args.homeDir ?? homedir();
-  const serviceName = autosyncServiceName(args.tool);
+  const rootDir =
+    args.rootDir ??
+    resolveCliContextRoot({ homeDir: home, cwd: process.cwd() });
+  const serviceName = autosyncServiceName(args.tool, rootDir, home);
   const config = await loadAutosyncConfig(serviceName, home);
   const state = await loadAutosyncRuntimeState(serviceName, home);
   const plistPath = autosyncPlistPath(home, serviceName);
@@ -853,8 +895,13 @@ export async function autosyncStatus(args: {
 
 export async function restartAutosyncService(args: {
   tool?: string;
+  rootDir?: string;
 }): Promise<void> {
-  const serviceName = autosyncServiceName(args.tool);
+  const home = homedir();
+  const rootDir =
+    args.rootDir ??
+    resolveCliContextRoot({ homeDir: home, cwd: process.cwd() });
+  const serviceName = autosyncServiceName(args.tool, rootDir, home);
   const label = autosyncLabel(serviceName);
   await runLaunchctl(["kickstart", "-k", `${launchdDomain()}/${label}`]);
 }
@@ -867,21 +914,37 @@ export async function autosyncCommand(argv: string[]) {
   }
 
   try {
+    const parsed = parseCliContextArgs(rest);
+    if (
+      parsed.argv.includes("--help") ||
+      parsed.argv.includes("-h") ||
+      parsed.argv[0] === "help"
+    ) {
+      console.log(autosyncHelp());
+      return;
+    }
+    const rootDir = resolveCliContextRoot({
+      rootArg: parsed.rootArg,
+      scope: parsed.scope,
+      cwd: process.cwd(),
+    });
+
     if (sub === "install") {
-      const tool = parseAutosyncPositionals(rest, [
+      const tool = parseAutosyncPositionals(parsed.argv, [
         "--git-remote",
         "--git-branch",
         "--git-interval-minutes",
       ])[0];
-      const gitRemote = parseAutosyncStringFlag(rest, "--git-remote");
-      const gitBranch = parseAutosyncStringFlag(rest, "--git-branch");
+      const gitRemote = parseAutosyncStringFlag(parsed.argv, "--git-remote");
+      const gitBranch = parseAutosyncStringFlag(parsed.argv, "--git-branch");
       const gitIntervalMinutes = parseAutosyncIntFlag(
-        rest,
+        parsed.argv,
         "--git-interval-minutes"
       );
-      const gitEnabled = !rest.includes("--git-disable");
+      const gitEnabled = !parsed.argv.includes("--git-disable");
       const config = await installAutosyncService({
         tool,
+        rootDir,
         gitRemote,
         gitBranch,
         gitIntervalMinutes,
@@ -893,16 +956,18 @@ export async function autosyncCommand(argv: string[]) {
     }
 
     if (sub === "uninstall") {
-      const tool = parseAutosyncPositionals(rest, [])[0];
-      await uninstallAutosyncService({ tool });
-      console.log(`Removed autosync service: ${autosyncServiceName(tool)}`);
+      const tool = parseAutosyncPositionals(parsed.argv, [])[0];
+      await uninstallAutosyncService({ tool, rootDir });
+      console.log(
+        `Removed autosync service: ${autosyncServiceName(tool, rootDir)}`
+      );
       return;
     }
 
     if (sub === "status") {
-      const tool = parseAutosyncPositionals(rest, [])[0];
-      const status = await autosyncStatus({ tool });
-      console.log(`Service: ${autosyncServiceName(tool)}`);
+      const tool = parseAutosyncPositionals(parsed.argv, [])[0];
+      const status = await autosyncStatus({ tool, rootDir });
+      console.log(`Service: ${autosyncServiceName(tool, rootDir)}`);
       console.log(`Plist: ${status.plistPath}`);
       console.log(`Installed: ${status.plistExists ? "yes" : "no"}`);
       console.log(`Loaded: ${status.loaded ? "yes" : "no"}`);
@@ -933,21 +998,25 @@ export async function autosyncCommand(argv: string[]) {
     }
 
     if (sub === "restart") {
-      const tool = parseAutosyncPositionals(rest, [])[0];
-      await restartAutosyncService({ tool });
-      console.log(`Restarted autosync service: ${autosyncServiceName(tool)}`);
+      const tool = parseAutosyncPositionals(parsed.argv, [])[0];
+      await restartAutosyncService({ tool, rootDir });
+      console.log(
+        `Restarted autosync service: ${autosyncServiceName(tool, rootDir)}`
+      );
       return;
     }
 
     if (sub === "run") {
-      const service = parseAutosyncStringFlag(rest, "--service");
-      const tool = parseAutosyncPositionals(rest, ["--service"])[0];
-      const serviceName = service ?? autosyncServiceName(tool);
+      const service = parseAutosyncStringFlag(parsed.argv, "--service");
+      const tool = parseAutosyncPositionals(parsed.argv, ["--service"])[0];
+      const serviceName = service ?? autosyncServiceName(tool, rootDir);
       const config = await loadAutosyncConfig(serviceName);
       if (!config) {
         throw new Error(`Autosync service not configured: ${serviceName}`);
       }
-      await runAutosyncService(config, { once: rest.includes("--once") });
+      await runAutosyncService(config, {
+        once: parsed.argv.includes("--once"),
+      });
       return;
     }
 

package/src/builtin.ts

@@ -0,0 +1,61 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function facultBuiltinPackRoot(
+  packName = "facult-operating-model"
+): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return join(here, "..", "assets", "packs", packName);
+}
+
+async function readTomlObject(
+  pathValue: string
+): Promise<Record<string, unknown> | null> {
+  const file = Bun.file(pathValue);
+  if (!(await file.exists())) {
+    return null;
+  }
+  const parsed = Bun.TOML.parse(await file.text());
+  return isPlainObject(parsed) ? parsed : null;
+}
+
+function readBooleanConfig(
+  data: Record<string, unknown> | null,
+  key: string
+): boolean | null {
+  if (!data) {
+    return null;
+  }
+  const builtin = data.builtin;
+  if (!isPlainObject(builtin)) {
+    return null;
+  }
+  const value = builtin[key];
+  return typeof value === "boolean" ? value : null;
+}
+
+export async function builtinSyncDefaultsEnabled(
+  rootDir: string
+): Promise<boolean> {
+  const [tracked, local] = await Promise.all([
+    readTomlObject(join(rootDir, "config.toml")),
+    readTomlObject(join(rootDir, "config.local.toml")),
+  ]);
+
+  for (const candidate of [tracked, local]) {
+    const direct = readBooleanConfig(candidate, "sync_defaults");
+    if (direct != null) {
+      return direct;
+    }
+    const legacy = readBooleanConfig(candidate, "sync_global_defaults");
+    if (legacy != null) {
+      return legacy;
+    }
+  }
+
+  return true;
+}

package/src/cli-context.ts

@@ -0,0 +1,198 @@
+import { resolve } from "node:path";
+import type { AssetSourceKind } from "./graph";
+import {
+  facultContextRootDir,
+  facultRootDir,
+  findNearestProjectAiRoot,
+  projectRootFromAiRoot,
+} from "./paths";
+
+export type CapabilityScopeMode = "merged" | "global" | "project";
+
+export interface ParsedCliContext {
+  argv: string[];
+  rootArg?: string;
+  scope: CapabilityScopeMode;
+  sourceKind?: AssetSourceKind;
+}
+
+function expandHomePath(pathValue: string, home: string): string {
+  if (pathValue === "~") {
+    return home;
+  }
+  if (pathValue.startsWith("~/")) {
+    return `${home}/${pathValue.slice(2)}`;
+  }
+  return pathValue;
+}
+
+function resolveRootArgument(pathValue: string, homeDir: string): string {
+  return resolve(expandHomePath(pathValue, homeDir));
+}
+
+function parseStringFlagValue(
+  arg: string,
+  nextArg: string | undefined,
+  flag: string
+): { value: string; advance: number } | null {
+  if (arg === flag) {
+    if (!nextArg) {
+      throw new Error(`${flag} requires a value`);
+    }
+    return { value: nextArg, advance: 1 };
+  }
+  if (arg.startsWith(`${flag}=`)) {
+    const value = arg.slice(flag.length + 1);
+    if (!value) {
+      throw new Error(`${flag} requires a value`);
+    }
+    return { value, advance: 0 };
+  }
+  return null;
+}
+
+function parseScopeValue(value: string): CapabilityScopeMode {
+  if (value === "merged" || value === "global" || value === "project") {
+    return value;
+  }
+  throw new Error(`Unknown scope: ${value}`);
+}
+
+function parseSourceValue(value: string): AssetSourceKind {
+  if (value === "builtin" || value === "global" || value === "project") {
+    return value;
+  }
+  throw new Error(`Unknown source: ${value}`);
+}
+
+export function parseCliContextArgs(
+  argv: string[],
+  opts?: { allowSource?: boolean; allowScope?: boolean }
+): ParsedCliContext {
+  const rest: string[] = [];
+  let rootArg: string | undefined;
+  let scope: CapabilityScopeMode = "merged";
+  let sourceKind: AssetSourceKind | undefined;
+  let explicitRoot = false;
+  let explicitScope = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg) {
+      continue;
+    }
+
+    const root = parseStringFlagValue(arg, argv[i + 1], "--root");
+    if (root) {
+      if (explicitRoot) {
+        throw new Error("--root may only be provided once");
+      }
+      rootArg = root.value;
+      explicitRoot = true;
+      i += root.advance;
+      continue;
+    }
+
+    if (arg === "--global") {
+      if (explicitScope && scope !== "global") {
+        throw new Error("Conflicting scope flags");
+      }
+      scope = "global";
+      explicitScope = true;
+      continue;
+    }
+
+    if (arg === "--project") {
+      if (explicitScope && scope !== "project") {
+        throw new Error("Conflicting scope flags");
+      }
+      scope = "project";
+      explicitScope = true;
+      continue;
+    }
+
+    if (opts?.allowScope !== false) {
+      const parsedScope = parseStringFlagValue(arg, argv[i + 1], "--scope");
+      if (parsedScope) {
+        const value = parseScopeValue(parsedScope.value);
+        if (explicitScope && scope !== value) {
+          throw new Error("Conflicting scope flags");
+        }
+        scope = value;
+        explicitScope = true;
+        i += parsedScope.advance;
+        continue;
+      }
+    }
+
+    if (opts?.allowSource) {
+      const parsedSource = parseStringFlagValue(arg, argv[i + 1], "--source");
+      if (parsedSource) {
+        sourceKind = parseSourceValue(parsedSource.value);
+        i += parsedSource.advance;
+        continue;
+      }
+    }
+
+    rest.push(arg);
+  }
+
+  return {
+    argv: rest,
+    rootArg,
+    scope,
+    sourceKind,
+  };
+}
+
+function coerceCanonicalRoot(pathValue: string, homeDir: string): string {
+  const resolved = resolveRootArgument(pathValue, homeDir);
+  const nearestProjectAi = findNearestProjectAiRoot(resolved);
+  if (nearestProjectAi) {
+    const projectRoot = projectRootFromAiRoot(nearestProjectAi, homeDir);
+    if (
+      resolved === nearestProjectAi ||
+      resolved === resolve(projectRoot ?? "")
+    ) {
+      return nearestProjectAi;
+    }
+  }
+  return resolved;
+}
+
+export function resolveCliContextRoot(args?: {
+  homeDir?: string;
+  cwd?: string;
+  rootArg?: string;
+  scope?: CapabilityScopeMode;
+}): string {
+  const homeDir = args?.homeDir ?? process.env.HOME ?? "";
+  const cwd = args?.cwd ?? process.cwd();
+  const scope = args?.scope ?? "merged";
+
+  if (args?.rootArg) {
+    const rootDir = coerceCanonicalRoot(args.rootArg, homeDir);
+    if (scope === "project" && !projectRootFromAiRoot(rootDir, homeDir)) {
+      throw new Error(
+        `Project scope requires a repo-local .ai root: ${rootDir}`
+      );
+    }
+    return rootDir;
+  }
+
+  if (scope === "global") {
+    return facultRootDir(homeDir);
+  }
+
+  if (scope === "project") {
+    const projectRoot = findNearestProjectAiRoot(cwd);
+    if (!projectRoot) {
+      throw new Error(
+        "No project-local .ai root found from the current directory"
+      );
+    }
+    return projectRoot;
+  }
+
+  return facultContextRootDir({ home: homeDir, cwd });
+}

package/src/enable-disable.ts

@@ -37,6 +37,7 @@ function ensureIndexStructure(index: FacultIndex): FacultIndex {
     mcp: index.mcp ?? { servers: {} },
     agents: index.agents ?? {},
     snippets: index.snippets ?? {},
+    instructions: index.instructions ?? {},
   };
 }
 

package/src/global-docs.ts

@@ -1,12 +1,15 @@
 import { mkdir, readdir, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { renderCanonicalText } from "./agents";
+import { builtinSyncDefaultsEnabled, facultBuiltinPackRoot } from "./builtin";
+import { projectRootFromAiRoot } from "./paths";
 import { renderSnippetText } from "./snippets";
 
 export interface GlobalDocPlan {
   write: string[];
   remove: string[];
   contents: Map<string, string>;
+  sources: Map<string, string>;
   managedTargets: string[];
 }
 
@@ -14,6 +17,7 @@ export interface RulesPlan {
   write: string[];
   remove: string[];
   contents: Map<string, string>;
+  sources: Map<string, string>;
   managedRulesDir: boolean;
 }
 
@@ -22,6 +26,7 @@ export interface ToolConfigPlan {
   write: boolean;
   remove: boolean;
   contents: string | null;
+  sourcePath?: string;
   managedConfig: boolean;
 }
 
@@ -30,6 +35,11 @@ interface SourceTarget {
   targetPath: string;
 }
 
+interface GlobalDocTargetPaths {
+  primary: string;
+  override?: string;
+}
+
 const TOML_BARE_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -151,30 +161,53 @@ async function listGlobalDocSources(args: {
   toolHome: string;
 }): Promise<SourceTarget[]> {
   const { rootDir, tool, toolHome } = args;
-  if (tool !== "codex") {
-    return [];
-  }
+  const targets = globalDocTargetPaths(tool, toolHome);
+  const useBuiltinDefaults = await builtinSyncDefaultsEnabled(rootDir);
 
   const candidates: SourceTarget[] = [];
   const base = join(rootDir, "AGENTS.global.md");
   if (await fileExists(base)) {
     candidates.push({
       sourcePath: base,
-      targetPath: join(toolHome, "AGENTS.md"),
+      targetPath: targets.primary,
     });
+  } else if (useBuiltinDefaults) {
+    const builtinBase = join(facultBuiltinPackRoot(), "AGENTS.global.md");
+    if (await fileExists(builtinBase)) {
+      candidates.push({
+        sourcePath: builtinBase,
+        targetPath: targets.primary,
+      });
+    }
   }
 
   const override = join(rootDir, "AGENTS.override.global.md");
-  if (await fileExists(override)) {
+  if (targets.override && (await fileExists(override))) {
     candidates.push({
       sourcePath: override,
-      targetPath: join(toolHome, "AGENTS.override.md"),
+      targetPath: targets.override,
     });
   }
 
   return candidates;
 }
 
+export function globalDocTargetPaths(
+  tool: string,
+  toolHome: string
+): GlobalDocTargetPaths {
+  if (tool === "claude") {
+    return {
+      primary: join(toolHome, "CLAUDE.md"),
+    };
+  }
+
+  return {
+    primary: join(toolHome, "AGENTS.md"),
+    override: join(toolHome, "AGENTS.override.md"),
+  };
+}
+
 async function renderSourceTarget(args: {
   homeDir: string;
   rootDir: string;
@@ -194,6 +227,7 @@ async function renderSourceTarget(args: {
   return await renderCanonicalText(withSnippets.text, {
     homeDir: args.homeDir,
     rootDir: args.rootDir,
+    projectRoot: projectRootFromAiRoot(args.rootDir, args.homeDir) ?? undefined,
     targetTool: args.tool,
     targetPath: args.targetPath,
   });
@@ -208,6 +242,7 @@ export async function planToolGlobalDocsSync(args: {
 }): Promise<GlobalDocPlan> {
   const docs = await listGlobalDocSources(args);
   const contents = new Map<string, string>();
+  const sources = new Map<string, string>();
   const managedTargets = docs.map((doc) => doc.targetPath).sort();
 
   for (const doc of docs) {
@@ -219,6 +254,7 @@ export async function planToolGlobalDocsSync(args: {
       tool: args.tool,
     });
     contents.set(doc.targetPath, rendered);
+    sources.set(doc.targetPath, doc.sourcePath);
   }
 
   const write: string[] = [];
@@ -238,6 +274,7 @@ export async function planToolGlobalDocsSync(args: {
     write: write.sort(),
     remove,
     contents,
+    sources,
     managedTargets,
   };
 }
@@ -301,6 +338,7 @@ export async function planToolRulesSync(args: {
 }): Promise<RulesPlan> {
   const rules = await listToolRules(args);
   const contents = new Map<string, string>();
+  const sources = new Map<string, string>();
 
   for (const rule of rules) {
     const targetPath = join(args.rulesDir, rule.targetPath);
@@ -308,10 +346,13 @@ export async function planToolRulesSync(args: {
     const rendered = await renderCanonicalText(raw, {
       homeDir: args.homeDir,
       rootDir: args.rootDir,
+      projectRoot:
+        projectRootFromAiRoot(args.rootDir, args.homeDir) ?? undefined,
       targetTool: args.tool,
       targetPath,
     });
     contents.set(targetPath, rendered);
+    sources.set(targetPath, rule.sourcePath);
   }
 
   const write: string[] = [];
@@ -342,6 +383,7 @@ export async function planToolRulesSync(args: {
     write: write.sort(),
     remove: remove.sort(),
     contents,
+    sources,
     managedRulesDir: rules.length > 0,
   };
 }
@@ -390,6 +432,7 @@ export async function planToolConfigSync(args: {
       write: false,
       remove: false,
       contents: null,
+      sourcePath,
       managedConfig: false,
     };
   }
@@ -419,6 +462,7 @@ export async function planToolConfigSync(args: {
     write: current !== `${nextContents}\n`,
     remove: false,
     contents: nextContents,
+    sourcePath,
     managedConfig: true,
   };
 }