facult 2.3.1 → 2.4.0

package/README.md

@@ -260,9 +260,17 @@ fclt index
 
 Why `keep-current`: it is deterministic and non-interactive for duplicate sources.
 
-Canonical source root: `~/.ai` for global work, or `<repo>/.ai` for project-local work. Facult-owned generated/config/runtime state lives inside the active canonical root:
-- global: `~/.ai/.facult`
-- project: `<repo>/.ai/.facult`
+Canonical source root: `~/.ai` for global work, or `<repo>/.ai` for project-local work.
+
+Generated AI state that belongs with the canonical root lives inside that root:
+- global: `~/.ai/.facult/ai/...`
+- project: `<repo>/.ai/.facult/ai/...`
+
+Machine-local operational state lives outside the canonical root:
+- macOS state: `~/Library/Application Support/fclt/...`
+- macOS cache: `~/Library/Caches/fclt/...`
+- Linux/other state: `${XDG_STATE_HOME:-~/.local/state}/fclt/...`
+- Linux/other cache: `${XDG_CACHE_HOME:-~/.cache}/fclt/...`
 
 ### 3b. Bootstrap a repo-local `.ai`
 
@@ -420,7 +428,8 @@ Typical layout:
 
 Important split:
 - `.ai/` is canonical source
-- `.ai/.facult/` is Facult-owned generated state, trust state, managed tool state, autosync state, and caches
+- `.ai/.facult/ai/` is generated AI state that belongs with the canonical root
+- machine-local Facult state such as managed-tool state, autosync runtime/config, install metadata, and launcher caches lives outside `.ai/`
 - tool homes such as `.codex/` and `.claude/` are rendered outputs
 - the generated capability graph lives at `.ai/.facult/ai/graph.json`
 
@@ -714,6 +723,13 @@ Files are written to:
 - `~/.codex/automations/<name>/automation.toml`
 - `~/.codex/automations/<name>/memory.md`
 
+When Codex is in managed mode, canonical automation sources live under:
+
+- `~/.ai/automations/<name>/...` for global automation state
+- `<repo>/.ai/automations/<name>/...` for project-scoped canonical state
+
+Managed sync renders those canonical automation directories into the shared live Codex automation store at `~/.codex/automations/` and only removes automation files that were previously rendered by the same canonical root.
+
 Example project automation:
 
 ```bash
@@ -774,17 +790,21 @@ fclt <command> --help
 
 ### State and report files
 
-Under `~/.ai/.facult/`:
+Under canonical generated AI state (`~/.ai/.facult/` or `<repo>/.ai/.facult/`):
 - `sources.json` (latest inventory scan state)
 - `consolidated.json` (consolidation state)
-- `managed.json` (managed tool state)
 - `ai/index.json` (generated canonical AI inventory)
 - `audit/static-latest.json` (latest static audit report)
 - `audit/agent-latest.json` (latest agent audit report)
 - `trust/sources.json` (source trust policy state)
-- `autosync/services/*.json` (autosync service configs)
-- `autosync/state/*.json` (autosync runtime state)
-- `autosync/logs/*` (autosync service logs)
+
+Under machine-local Facult state:
+- `install.json` (machine-local install metadata)
+- `global/managed.json` or `projects/<slug-hash>/managed.json` (managed tool state)
+- `.../autosync/services/*.json` (autosync service configs)
+- `.../autosync/state/*.json` (autosync runtime state)
+- `.../autosync/logs/*` (autosync service logs)
+- `runtime/<version>/<platform-arch>/...` under the machine-local cache root (npm launcher binary cache)
 
 ### Config reference
 
@@ -890,7 +910,7 @@ Release behavior:
 4. npm publish runs only after binary asset upload succeeds (`publish-npm` depends on `publish-assets`).
 5. Published release assets include platform binaries, `fclt-install.sh`, `facult-install.sh`, and `SHA256SUMS`.
 6. When `HOMEBREW_TAP_TOKEN` is configured, the release workflow also updates the Homebrew tap at `hack-dance/homebrew-tap`.
-7. The npm package launcher resolves your platform, downloads the matching release binary, caches it under `~/.ai/.facult/runtime/<version>/<platform-arch>/`, and runs it.
+7. The npm package launcher resolves your platform, downloads the matching release binary, caches it under the machine-local cache root (`~/Library/Caches/fclt/runtime/...` on macOS or `${XDG_CACHE_HOME:-~/.cache}/fclt/runtime/...` elsewhere), and runs it.
 
 Current prebuilt binary targets:
 - `darwin-x64`

package/bin/fclt.cjs

@@ -16,6 +16,43 @@ const PACKAGE_NAME = "facult";
 const DOWNLOAD_RETRIES = 12;
 const DOWNLOAD_RETRY_DELAY_MS = 5000;
 
+function isHelpLikeArgs(args) {
+  return (
+    args.length === 0 ||
+    args.includes("--help") ||
+    args.includes("-h") ||
+    args[0] === "help"
+  );
+}
+
+function localStateRoot(home) {
+  const override = String(process.env.FACULT_LOCAL_STATE_DIR || "").trim();
+  if (override) {
+    return path.resolve(override);
+  }
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Application Support", "fclt");
+  }
+  const xdg = String(process.env.XDG_STATE_HOME || "").trim();
+  return xdg
+    ? path.join(path.resolve(xdg), "fclt")
+    : path.join(home, ".local", "state", "fclt");
+}
+
+function localCacheRoot(home) {
+  const override = String(process.env.FACULT_CACHE_DIR || "").trim();
+  if (override) {
+    return path.resolve(override);
+  }
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Caches", "fclt");
+  }
+  const xdg = String(process.env.XDG_CACHE_HOME || "").trim();
+  return xdg
+    ? path.join(path.resolve(xdg), "fclt")
+    : path.join(home, ".cache", "fclt");
+}
+
 async function main() {
   const resolved = resolveTarget();
   if (!resolved.ok) {
@@ -30,7 +67,7 @@ async function main() {
   }
 
   const home = os.homedir();
-  const cacheRoot = path.join(home, ".ai", ".facult", "runtime");
+  const cacheRoot = path.join(localCacheRoot(home), "runtime");
   const installDir = path.join(
     cacheRoot,
     version,
@@ -39,9 +76,34 @@ async function main() {
   const binaryName = resolved.platform === "windows" ? "fclt.exe" : "fclt";
   const binaryPath = path.join(installDir, binaryName);
   const sourceEntry = path.join(__dirname, "..", "src", "index.ts");
+  const args = process.argv.slice(2);
   let installedBinaryThisRun = false;
 
   if (!(await fileExists(binaryPath))) {
+    const packageManager = detectPackageManager();
+    const hasSourceFallback = await canUseSourceFallback(sourceEntry);
+    const incompleteCache = await hasIncompleteRuntimeCache({
+      installDir,
+      binaryName,
+    });
+
+    if (incompleteCache) {
+      await removeIncompleteRuntimeTemps({ installDir, binaryName });
+    }
+
+    if (hasSourceFallback && (incompleteCache || isHelpLikeArgs(args))) {
+      return runSourceFallback({
+        sourceEntry,
+        version,
+        packageManager,
+        reason: new Error(
+          incompleteCache
+            ? "incomplete cached runtime download"
+            : "runtime binary missing for help-like command"
+        ),
+      });
+    }
+
     const tag = `v${version}`;
     const assetName = `${PACKAGE_NAME}-${version}-${resolved.platform}-${resolved.arch}${resolved.ext}`;
     const url = `https://github.com/${REPO_OWNER}/${REPO_NAME}/releases/download/${tag}/${assetName}`;
@@ -95,7 +157,6 @@ async function main() {
     });
   }
 
-  const args = process.argv.slice(2);
   const result = spawnSync(binaryPath, args, {
     stdio: "inherit",
     env: {
@@ -281,6 +342,28 @@ async function fileExists(filePath) {
   }
 }
 
+async function hasIncompleteRuntimeCache({ installDir, binaryName }) {
+  try {
+    const entries = await fsp.readdir(installDir);
+    return entries.some((entry) => entry.startsWith(`${binaryName}.tmp-`));
+  } catch {
+    return false;
+  }
+}
+
+async function removeIncompleteRuntimeTemps({ installDir, binaryName }) {
+  try {
+    const entries = await fsp.readdir(installDir);
+    await Promise.all(
+      entries
+        .filter((entry) => entry.startsWith(`${binaryName}.tmp-`))
+        .map((entry) => safeUnlink(path.join(installDir, entry)))
+    );
+  } catch {
+    // Ignore missing runtime dirs while cleaning stale temp files.
+  }
+}
+
 async function safeUnlink(filePath) {
   try {
     await fsp.unlink(filePath);
@@ -295,7 +378,7 @@ function sleep(ms) {
 
 async function writeInstallState(state) {
   const home = os.homedir();
-  const installStateDir = path.join(home, ".ai", ".facult");
+  const installStateDir = localStateRoot(home);
   const installStatePath = path.join(installStateDir, "install.json");
   await fsp.mkdir(installStateDir, { recursive: true });
   await fsp.writeFile(

package/package.json

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

package/src/autosync.ts

@@ -5,6 +5,7 @@ import { basename, dirname, join } from "node:path";
 import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
 import { syncManagedTools } from "./manage";
 import {
+  facultMachineStateDir,
   facultRootDir,
   facultStateDir,
   legacyFacultStateDirForRoot,
@@ -84,6 +85,10 @@ interface GitSyncOutcome {
   message?: string;
 }
 
+let launchctlRunnerForTests:
+  | ((args: string[]) => Promise<CommandResult>)
+  | null = null;
+
 function nowIso(): string {
   return new Date().toISOString();
 }
@@ -100,6 +105,10 @@ function runDetached(context: string, promise: Promise<void>) {
 }
 
 function autosyncDir(home: string, rootDir?: string): string {
+  return join(facultMachineStateDir(home, rootDir), "autosync");
+}
+
+function canonicalAutosyncDir(home: string, rootDir?: string): string {
   return join(facultStateDir(home, rootDir), "autosync");
 }
 
@@ -155,11 +164,21 @@ function autosyncServiceName(
 }
 
 function autosyncLabel(serviceName: string): string {
+  return serviceName === "all"
+    ? "com.fclt.autosync"
+    : `com.fclt.autosync.${serviceName}`;
+}
+
+function legacyAutosyncLabel(serviceName: string): string {
   return serviceName === "all"
     ? "com.facult.autosync"
     : `com.facult.autosync.${serviceName}`;
 }
 
+function autosyncLabelCandidates(serviceName: string): string[] {
+  return [autosyncLabel(serviceName), legacyAutosyncLabel(serviceName)];
+}
+
 function autosyncPlistPath(home: string, serviceName: string): string {
   return join(
     home,
@@ -331,6 +350,11 @@ export async function loadAutosyncConfig(
 ): Promise<AutosyncServiceConfig | null> {
   const candidates = [
     autosyncConfigPath(homeDir, serviceName, rootDir),
+    join(
+      canonicalAutosyncDir(homeDir, rootDir),
+      "services",
+      `${serviceName}.json`
+    ),
     legacyAutosyncConfigPath(homeDir, serviceName, rootDir),
   ];
   for (const candidate of candidates) {
@@ -359,6 +383,11 @@ export async function loadAutosyncRuntimeState(
 ): Promise<AutosyncRuntimeState | null> {
   const candidates = [
     autosyncRuntimeStatePath(homeDir, serviceName, rootDir),
+    join(
+      canonicalAutosyncDir(homeDir, rootDir),
+      "state",
+      `${serviceName}.json`
+    ),
     legacyAutosyncRuntimeStatePath(homeDir, serviceName, rootDir),
   ];
   for (const candidate of candidates) {
@@ -399,9 +428,18 @@ async function runCommand(
 }
 
 async function runLaunchctl(args: string[]): Promise<CommandResult> {
+  if (launchctlRunnerForTests) {
+    return await launchctlRunnerForTests(args);
+  }
   return await runCommand(["launchctl", ...args]);
 }
 
+export function setLaunchctlRunnerForTests(
+  runner: ((args: string[]) => Promise<CommandResult>) | null
+) {
+  launchctlRunnerForTests = runner;
+}
+
 function launchdDomain(): string {
   return `gui/${process.getuid?.() ?? process.geteuid?.() ?? 0}`;
 }
@@ -470,6 +508,122 @@ async function ensureGitRepo(repoDir: string): Promise<boolean> {
   return await pathExists(join(repoDir, ".git"));
 }
 
+async function cleanupAutosyncLaunchAgentArtifacts(args: {
+  homeDir: string;
+  serviceName: string;
+}) {
+  const domain = launchdDomain();
+  for (const label of autosyncLabelCandidates(args.serviceName)) {
+    await runLaunchctl(["bootout", `${domain}/${label}`]).catch(() => null);
+  }
+
+  const legacyPlistPath = join(
+    args.homeDir,
+    "Library",
+    "LaunchAgents",
+    `${legacyAutosyncLabel(args.serviceName)}.plist`
+  );
+  if (legacyPlistPath !== autosyncPlistPath(args.homeDir, args.serviceName)) {
+    await rm(legacyPlistPath, { force: true });
+  }
+}
+
+async function cleanupLegacyAutosyncFiles(args: {
+  homeDir: string;
+  serviceName: string;
+  rootDir: string;
+}) {
+  const legacyPaths = [
+    join(
+      canonicalAutosyncDir(args.homeDir, args.rootDir),
+      "services",
+      `${args.serviceName}.json`
+    ),
+    join(
+      canonicalAutosyncDir(args.homeDir, args.rootDir),
+      "state",
+      `${args.serviceName}.json`
+    ),
+    join(
+      canonicalAutosyncDir(args.homeDir, args.rootDir),
+      "logs",
+      `${args.serviceName}.log`
+    ),
+    join(
+      canonicalAutosyncDir(args.homeDir, args.rootDir),
+      "logs",
+      `${args.serviceName}.err.log`
+    ),
+    legacyAutosyncConfigPath(args.homeDir, args.serviceName, args.rootDir),
+    legacyAutosyncRuntimeStatePath(
+      args.homeDir,
+      args.serviceName,
+      args.rootDir
+    ),
+  ];
+  for (const candidate of legacyPaths) {
+    await rm(candidate, { force: true }).catch(() => null);
+  }
+}
+
+const AUTOSYNC_REBUILDABLE_PATHS = [
+  ".facult/ai/index.json",
+  ".facult/ai/graph.json",
+];
+
+const AUTOSYNC_MACHINE_LOCAL_LEGACY_PATHS = [
+  ".facult/managed.json",
+  ".facult/install.json",
+  ".facult/autosync",
+  ".facult/runtime",
+];
+
+async function gitListTrackedPaths(
+  repoDir: string,
+  pathValue: string
+): Promise<string[]> {
+  const result = await runCommand(["git", "ls-files", "-z", "--", pathValue], {
+    cwd: repoDir,
+  });
+  if (result.exitCode !== 0 || !result.stdout) {
+    return [];
+  }
+  return result.stdout
+    .split("\0")
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+async function cleanupAutosyncProtectedPaths(repoDir: string): Promise<void> {
+  const tracked = new Set<string>();
+  for (const pathValue of [
+    ...AUTOSYNC_REBUILDABLE_PATHS,
+    ...AUTOSYNC_MACHINE_LOCAL_LEGACY_PATHS,
+  ]) {
+    for (const entry of await gitListTrackedPaths(repoDir, pathValue)) {
+      tracked.add(entry);
+    }
+    await rm(join(repoDir, pathValue), { force: true, recursive: true }).catch(
+      () => null
+    );
+  }
+
+  if (tracked.size > 0) {
+    await runCommand(
+      [
+        "git",
+        "restore",
+        "--staged",
+        "--worktree",
+        "--source=HEAD",
+        "--",
+        ...tracked,
+      ],
+      { cwd: repoDir }
+    );
+  }
+}
+
 export async function runGitAutosyncOnce(args: {
   config: AutosyncServiceConfig;
 }): Promise<GitSyncOutcome> {
@@ -503,6 +657,8 @@ export async function runGitAutosyncOnce(args: {
     };
   }
 
+  await cleanupAutosyncProtectedPaths(repoDir);
+
   const fetch = await runCommand(
     ["git", "fetch", config.git.remote, config.git.branch],
     { cwd: repoDir }
@@ -849,10 +1005,18 @@ export async function installAutosyncService(args: {
   await mkdir(dirname(spec.plistPath), { recursive: true });
   await mkdir(autosyncLogsDir(home, rootDir), { recursive: true });
   await saveAutosyncConfig(config, home);
+  await cleanupLegacyAutosyncFiles({
+    homeDir: home,
+    serviceName,
+    rootDir: config.rootDir,
+  });
+  await cleanupAutosyncLaunchAgentArtifacts({
+    homeDir: home,
+    serviceName,
+  });
   await writeFile(spec.plistPath, plist, "utf8");
 
   const domain = launchdDomain();
-  await runLaunchctl(["bootout", `${domain}/${spec.label}`]).catch(() => null);
   await runLaunchctl(["bootstrap", domain, spec.plistPath]);
   await runLaunchctl(["kickstart", "-k", `${domain}/${spec.label}`]);
   return config;
@@ -868,10 +1032,16 @@ export async function uninstallAutosyncService(args: {
     args.rootDir ??
     resolveCliContextRoot({ homeDir: home, cwd: process.cwd() });
   const serviceName = autosyncServiceName(args.tool, rootDir, home);
-  const label = autosyncLabel(serviceName);
-  const domain = launchdDomain();
 
-  await runLaunchctl(["bootout", `${domain}/${label}`]).catch(() => null);
+  await cleanupAutosyncLaunchAgentArtifacts({
+    homeDir: home,
+    serviceName,
+  });
+  await cleanupLegacyAutosyncFiles({
+    homeDir: home,
+    serviceName,
+    rootDir,
+  });
   await rm(autosyncPlistPath(home, serviceName), { force: true });
   await rm(autosyncConfigPath(home, serviceName, rootDir), { force: true });
 }
@@ -883,6 +1053,7 @@ export async function repairAutosyncServices(
   const activeRoot = rootDir ?? facultRootDir(homeDir);
   const serviceDirs = [
     autosyncServicesDir(homeDir, activeRoot),
+    join(canonicalAutosyncDir(homeDir, activeRoot), "services"),
     legacyAutosyncServicesDir(homeDir, activeRoot),
   ];
   const seen = new Set<string>();
@@ -916,6 +1087,11 @@ export async function repairAutosyncServices(
       await saveAutosyncConfig(config, homeDir);
       changed = true;
     }
+    await cleanupLegacyAutosyncFiles({
+      homeDir,
+      serviceName,
+      rootDir: config.rootDir,
+    });
 
     const spec = buildLaunchAgentSpec({
       homeDir,
@@ -923,19 +1099,27 @@ export async function repairAutosyncServices(
       rootDir: config.rootDir,
     });
     const desired = buildLaunchAgentPlist(spec);
+    const legacyPlistPath = join(
+      homeDir,
+      "Library",
+      "LaunchAgents",
+      `${legacyAutosyncLabel(serviceName)}.plist`
+    );
     const currentText = await readFile(spec.plistPath, "utf8").catch(
       () => null
     );
-    if (currentText !== desired) {
+    const legacyExists = await pathExists(legacyPlistPath);
+    if (currentText !== desired || legacyExists) {
       await mkdir(dirname(spec.plistPath), { recursive: true });
       await mkdir(autosyncLogsDir(homeDir, config.rootDir), {
         recursive: true,
       });
+      await cleanupAutosyncLaunchAgentArtifacts({
+        homeDir,
+        serviceName,
+      });
       await writeFile(spec.plistPath, desired, "utf8");
       const domain = launchdDomain();
-      await runLaunchctl(["bootout", `${domain}/${spec.label}`]).catch(
-        () => null
-      );
       await runLaunchctl(["bootstrap", domain, spec.plistPath]).catch(
         () => null
       );

package/src/index-builder.ts

@@ -14,7 +14,7 @@ import {
 import {
   facultAiGraphPath,
   facultAiIndexPath,
-  facultGeneratedStateDir,
+  facultMachineStateDir,
   facultRootDir,
   projectRootFromAiRoot,
   projectSlugFromAiRoot,
@@ -987,7 +987,7 @@ async function readManagedState(
   rootDir: string
 ): Promise<ManagedStateLite | null> {
   const statePath = join(
-    facultGeneratedStateDir({ home: homeDir, rootDir }),
+    facultMachineStateDir(homeDir, rootDir),
     "managed.json"
   );
   try {

package/src/manage.ts

@@ -32,7 +32,7 @@ import {
   type SkillEntry,
 } from "./index-builder";
 import {
-  facultGeneratedStateDir,
+  facultMachineStateDir,
   facultRootDir,
   legacyFacultStateDirForRoot,
   projectRootFromAiRoot,
@@ -44,6 +44,7 @@ export interface ManagedToolState {
   skillsDir?: string;
   mcpConfig?: string;
   agentsDir?: string;
+  automationDir?: string;
   toolHome?: string;
   globalAgentsPath?: string;
   globalAgentsOverridePath?: string;
@@ -75,6 +76,7 @@ export interface ToolPaths {
   skillsDir?: string;
   mcpConfig?: string;
   agentsDir?: string;
+  automationDir?: string;
   toolHome?: string;
   rulesDir?: string;
   toolConfig?: string;
@@ -163,6 +165,7 @@ function defaultToolPaths(
       skillsDir: toolBase(".codex", "skills"),
       mcpConfig: toolBase(".codex", "mcp.json"),
       agentsDir: toolBase(".codex", "agents"),
+      automationDir: homePath(home, ".codex", "automations"),
       toolHome: toolBase(".codex"),
       rulesDir: toolBase(".codex", "rules"),
       toolConfig: toolBase(".codex", "config.toml"),
@@ -293,7 +296,7 @@ export function managedStatePathForRoot(
   home: string = homedir(),
   rootDir?: string
 ): string {
-  return join(facultGeneratedStateDir({ home, rootDir }), "managed.json");
+  return join(facultMachineStateDir(home, rootDir), "managed.json");
 }
 
 function legacyManagedStatePathForRoot(
@@ -336,7 +339,7 @@ export async function saveManagedState(
   home: string = homedir(),
   rootDir?: string
 ) {
-  const dir = facultGeneratedStateDir({ home, rootDir });
+  const dir = facultMachineStateDir(home, rootDir);
   await ensureDir(dir);
   await Bun.write(
     managedStatePathForRoot(home, rootDir),
@@ -433,6 +436,104 @@ async function loadCanonicalAgents(
   return await loadAgentsFromRoot(homePath(rootDir, "agents"));
 }
 
+interface AutomationEntry {
+  name: string;
+  sourceDir: string;
+  files: Map<string, string>;
+}
+
+async function listRelativeFiles(root: string): Promise<string[]> {
+  const out: string[] = [];
+
+  async function visit(currentDir: string, prefix = ""): Promise<void> {
+    const entries = await readdir(currentDir, { withFileTypes: true }).catch(
+      () => [] as import("node:fs").Dirent[]
+    );
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) {
+        continue;
+      }
+      const relPath = prefix ? join(prefix, entry.name) : entry.name;
+      const fullPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        await visit(fullPath, relPath);
+        continue;
+      }
+      if (entry.isFile()) {
+        out.push(relPath);
+      }
+    }
+  }
+
+  await visit(root);
+  return out.sort();
+}
+
+async function loadAutomationEntries(
+  automationsRoot: string
+): Promise<AutomationEntry[]> {
+  const entries = await readdir(automationsRoot, { withFileTypes: true }).catch(
+    () => [] as import("node:fs").Dirent[]
+  );
+  const out: AutomationEntry[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith(".")) {
+      continue;
+    }
+    const sourceDir = join(automationsRoot, entry.name);
+    const relativeFiles = await listRelativeFiles(sourceDir);
+    const files = new Map<string, string>();
+    for (const relPath of relativeFiles) {
+      const raw = await readTextIfExists(join(sourceDir, relPath));
+      if (raw == null) {
+        continue;
+      }
+      files.set(relPath, raw);
+    }
+    if (!files.has("automation.toml")) {
+      continue;
+    }
+    out.push({
+      name: entry.name,
+      sourceDir,
+      files,
+    });
+  }
+
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+async function loadCanonicalAutomations(
+  rootDir: string
+): Promise<AutomationEntry[]> {
+  return await loadAutomationEntries(join(rootDir, "automations"));
+}
+
+function automationEntriesEqual(
+  left: AutomationEntry,
+  right: AutomationEntry
+): boolean {
+  if (left.files.size !== right.files.size) {
+    return false;
+  }
+  for (const [relPath, leftRaw] of left.files.entries()) {
+    if (right.files.get(relPath) !== leftRaw) {
+      return false;
+    }
+  }
+  return true;
+}
+
+async function canonicalAutomationsExist(rootDir: string): Promise<boolean> {
+  try {
+    const automations = await loadCanonicalAutomations(rootDir);
+    return automations.length > 0;
+  } catch {
+    return false;
+  }
+}
+
 async function loadMergedIndex(
   homeDir: string,
   rootDir: string
@@ -624,6 +725,58 @@ async function syncAgentFiles({
   return { add: plan.add, remove: plan.remove };
 }
 
+async function planAutomationFileChanges(args: {
+  automationDir: string;
+  rootDir: string;
+  previouslyManagedTargets?: string[];
+}): Promise<{
+  add: string[];
+  remove: string[];
+  contents: Map<string, string>;
+  sources: Map<string, string>;
+}> {
+  const automations = await loadCanonicalAutomations(args.rootDir);
+  const contents = new Map<string, string>();
+  const sources = new Map<string, string>();
+  const desiredPaths = 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);
+    }
+  }
+
+  const remove = Array.from(
+    new Set(
+      (args.previouslyManagedTargets ?? []).filter(
+        (targetPath) =>
+          targetPath.startsWith(join(args.automationDir, "")) &&
+          !desiredPaths.has(targetPath)
+      )
+    )
+  ).sort();
+
+  return {
+    add: Array.from(add).sort(),
+    remove,
+    contents,
+    sources,
+  };
+}
+
 async function listSkillDirs(skillsRoot: string): Promise<string[]> {
   try {
     const entries = await readdir(skillsRoot, { withFileTypes: true });
@@ -945,6 +1098,7 @@ interface ExistingManagedItem {
   kind:
     | "skill"
     | "agent"
+    | "automation"
     | "global-doc"
     | "rule"
     | "tool-config"
@@ -1123,6 +1277,87 @@ async function adoptExistingToolAgents(args: {
   return adopted;
 }
 
+async function planExistingAutomationAdoption(args: {
+  rootDir: string;
+  automationDir: string;
+}): Promise<ExistingManagedImportPlan> {
+  const plan = emptyManagedImportPlan();
+  const liveAutomations = await loadAutomationEntries(args.automationDir);
+  const canonicalAutomations = new Map(
+    (await loadCanonicalAutomations(args.rootDir)).map((entry) => [
+      entry.name,
+      entry,
+    ])
+  );
+
+  for (const liveAutomation of liveAutomations) {
+    const canonicalAutomation = canonicalAutomations.get(liveAutomation.name);
+    if (!canonicalAutomation) {
+      continue;
+    }
+    const item: ExistingManagedItem = {
+      kind: "automation",
+      name: liveAutomation.name,
+      livePath: liveAutomation.sourceDir,
+      canonicalPath: join(args.rootDir, "automations", liveAutomation.name),
+    };
+    if (automationEntriesEqual(liveAutomation, canonicalAutomation)) {
+      plan.identical.push(item);
+    } else {
+      plan.conflicts.push(item);
+    }
+  }
+
+  return mergeManagedImportPlans(plan);
+}
+
+async function adoptExistingAutomations(args: {
+  rootDir: string;
+  automationDir: string;
+  conflictMode: "keep-canonical" | "keep-existing";
+}): Promise<ExistingManagedItem[]> {
+  if (args.conflictMode !== "keep-existing") {
+    return [];
+  }
+
+  const adopted: ExistingManagedItem[] = [];
+  const liveAutomations = await loadAutomationEntries(args.automationDir);
+  const canonicalAutomations = new Map(
+    (await loadCanonicalAutomations(args.rootDir)).map((entry) => [
+      entry.name,
+      entry,
+    ])
+  );
+
+  for (const liveAutomation of liveAutomations) {
+    const canonicalAutomation = canonicalAutomations.get(liveAutomation.name);
+    if (
+      !(
+        canonicalAutomation &&
+        !automationEntriesEqual(liveAutomation, canonicalAutomation)
+      )
+    ) {
+      continue;
+    }
+    const canonicalPath = join(
+      args.rootDir,
+      "automations",
+      liveAutomation.name
+    );
+    await ensureDir(dirname(canonicalPath));
+    await rm(canonicalPath, { recursive: true, force: true });
+    await cp(liveAutomation.sourceDir, canonicalPath, { recursive: true });
+    adopted.push({
+      kind: "automation",
+      name: liveAutomation.name,
+      livePath: liveAutomation.sourceDir,
+      canonicalPath,
+    });
+  }
+
+  return adopted;
+}
+
 async function planExistingGlobalDocAdoption(args: {
   rootDir: string;
   tool: string;
@@ -1788,6 +2023,12 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
           agentsDir: toolPaths.agentsDir,
         })
       : emptyManagedImportPlan(),
+    toolPaths.automationDir
+      ? await planExistingAutomationAdoption({
+          rootDir,
+          automationDir: toolPaths.automationDir,
+        })
+      : emptyManagedImportPlan(),
     toolPaths.toolHome
       ? await planExistingGlobalDocAdoption({
           rootDir,
@@ -1826,6 +2067,7 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
   if (
     (toolPaths.skillsDir ||
       toolPaths.agentsDir ||
+      toolPaths.automationDir ||
       toolPaths.toolHome ||
       toolPaths.rulesDir ||
       toolPaths.toolConfig ||
@@ -1906,6 +2148,14 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
     });
     adoptedSkills.push(...result.map((item) => item.name));
   }
+  if (toolPaths.automationDir && opts.adoptExisting) {
+    const result = await adoptExistingAutomations({
+      rootDir,
+      automationDir: toolPaths.automationDir,
+      conflictMode: importConflictMode,
+    });
+    adoptedSkills.push(...result.map((item) => `${item.kind}:${item.name}`));
+  }
   if (toolPaths.toolHome && opts.adoptExisting) {
     const result = await adoptExistingGlobalDocs({
       rootDir,
@@ -1957,6 +2207,12 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
         tool,
       })
     : null;
+  const automationPreview = toolPaths.automationDir
+    ? await planAutomationFileChanges({
+        automationDir: toolPaths.automationDir,
+        rootDir,
+      })
+    : null;
   const globalDocsPreview = toolPaths.toolHome
     ? await planToolGlobalDocsSync({
         homeDir: home,
@@ -2048,6 +2304,16 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
     });
   }
 
+  if (toolPaths.automationDir && automationPreview) {
+    await ensureDir(toolPaths.automationDir);
+    await applyRenderedRemoves(automationPreview.remove);
+    await applyRenderedWrites({
+      contents: automationPreview.contents,
+      targets: Array.from(automationPreview.contents.keys()),
+    });
+    await pruneEmptyParents(automationPreview.remove, toolPaths.automationDir);
+  }
+
   if (toolPaths.toolHome && globalDocsPreview) {
     await ensureDir(toolPaths.toolHome);
     await applyRenderedRemoves(globalDocsPreview.remove);
@@ -2086,6 +2352,7 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
     skillsDir: toolPaths.skillsDir,
     mcpConfig: toolPaths.mcpConfig,
     agentsDir: toolPaths.agentsDir,
+    automationDir: toolPaths.automationDir,
     toolHome: globalDocsPreview?.managedTargets.length
       ? toolPaths.toolHome
       : undefined,
@@ -2123,6 +2390,15 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
       sources: agentPreview.sources,
     });
   }
+  if (automationPreview) {
+    updateRenderedTargetState({
+      entry: managedEntry,
+      writtenTargets: Array.from(automationPreview.contents.keys()),
+      removedTargets: automationPreview.remove,
+      contents: automationPreview.contents,
+      sources: automationPreview.sources,
+    });
+  }
   if (globalDocsPreview) {
     updateRenderedTargetState({
       entry: managedEntry,
@@ -2238,6 +2514,14 @@ export async function unmanageTool(tool: string, opts: ManageOptions = {}) {
     });
   }
 
+  if (entry.automationDir) {
+    const automationTargets = Object.keys(entry.renderedTargets ?? {}).filter(
+      (targetPath) => targetPath.startsWith(join(entry.automationDir!, ""))
+    );
+    await applyRenderedRemoves(automationTargets);
+    await pruneEmptyParents(automationTargets, entry.automationDir);
+  }
+
   if (entry.globalAgentsPath) {
     await restoreBackup({
       original: entry.globalAgentsPath,
@@ -2320,6 +2604,15 @@ async function repairManagedToolEntry(args: {
     changed = true;
   }
 
+  if (
+    !next.automationDir &&
+    toolPaths.automationDir &&
+    (await canonicalAutomationsExist(rootDir))
+  ) {
+    next.automationDir = toolPaths.automationDir;
+    changed = true;
+  }
+
   if (toolPaths.toolHome && !next.toolHome) {
     const preview = await syncToolGlobalDocs({
       homeDir,
@@ -2406,6 +2699,7 @@ async function planRenderedTargetConflicts(args: {
   desiredContents: Map<string, string>;
   desiredSources: Map<string, string>;
   conflictMode?: "warn" | "overwrite";
+  protectAllSources?: boolean;
 }): Promise<RenderedApplyPlan> {
   if (args.conflictMode === "overwrite") {
     return {
@@ -2433,7 +2727,7 @@ async function planRenderedTargetConflicts(args: {
       continue;
     }
     const sourceKind = renderedSourceKindForPath(sourcePath);
-    if (sourceKind !== "builtin") {
+    if (sourceKind !== "builtin" && !args.protectAllSources) {
       if (args.desiredWrites.includes(targetPath)) {
         write.push(targetPath);
       } else {
@@ -2452,8 +2746,16 @@ async function planRenderedTargetConflicts(args: {
     }
 
     const currentHash = renderedHash(current);
+    const desiredHash = args.desiredContents.get(targetPath)
+      ? renderedHash(args.desiredContents.get(targetPath)!)
+      : null;
     if (prior?.hash) {
-      if (currentHash === prior.hash) {
+      if (
+        currentHash === prior.hash ||
+        (args.desiredWrites.includes(targetPath) &&
+          desiredHash != null &&
+          currentHash === desiredHash)
+      ) {
         if (args.desiredWrites.includes(targetPath)) {
           write.push(targetPath);
         } else {
@@ -2470,6 +2772,15 @@ async function planRenderedTargetConflicts(args: {
       continue;
     }
 
+    if (
+      args.desiredWrites.includes(targetPath) &&
+      desiredHash != null &&
+      currentHash === desiredHash
+    ) {
+      write.push(targetPath);
+      continue;
+    }
+
     conflicts.push({
       targetPath,
       sourcePath,
@@ -2496,8 +2807,14 @@ function logRenderedConflicts(
       conflict.reason === "unknown_state"
         ? "no prior managed hash is recorded"
         : "local edits were detected";
+    const surface =
+      conflict.sourceKind === "builtin"
+        ? "builtin-backed target"
+        : "managed target";
     console.warn(
-      `${tool}: ${verb} builtin-backed target ${conflict.targetPath} because ${state}. Rerun with "--builtin-conflicts overwrite" to replace it with the latest packaged default.`
+      conflict.sourceKind === "builtin"
+        ? `${tool}: ${verb} ${surface} ${conflict.targetPath} because ${state}. Rerun with "--builtin-conflicts overwrite" to replace it with the latest packaged default.`
+        : `${tool}: ${verb} ${surface} ${conflict.targetPath} because ${state}.`
     );
   }
 }
@@ -2525,6 +2842,24 @@ async function applyRenderedRemoves(targets: string[]) {
   }
 }
 
+async function pruneEmptyParents(targets: string[], stopDir: string) {
+  const candidateDirs = Array.from(
+    new Set(targets.map((pathValue) => dirname(pathValue)))
+  ).sort((a, b) => b.length - a.length);
+
+  for (const startDir of candidateDirs) {
+    let currentDir = startDir;
+    while (currentDir.startsWith(join(stopDir, "")) && currentDir !== stopDir) {
+      const entries = await readdir(currentDir).catch(() => null);
+      if (!(entries && entries.length === 0)) {
+        break;
+      }
+      await rm(currentDir, { recursive: true, force: true });
+      currentDir = dirname(currentDir);
+    }
+  }
+}
+
 function updateRenderedTargetState(args: {
   entry: ManagedToolState;
   writtenTargets: string[];
@@ -2558,6 +2893,8 @@ function logSyncDryRun({
   mcpPlan,
   agentPlan,
   agentConflicts,
+  automationPlan,
+  automationConflicts,
   globalDocsPlan,
   globalDocsConflicts,
   rulesPlan,
@@ -2571,6 +2908,8 @@ function logSyncDryRun({
   mcpPlan: { needsWrite: boolean };
   agentPlan: { add: string[]; remove: string[] };
   agentConflicts: RenderedConflict[];
+  automationPlan: { write: string[]; remove: string[] };
+  automationConflicts: RenderedConflict[];
   globalDocsPlan: { write: string[]; remove: string[] };
   globalDocsConflicts: RenderedConflict[];
   rulesPlan: { write: string[]; remove: string[] };
@@ -2591,6 +2930,13 @@ function logSyncDryRun({
     console.log(`${tool}: would remove agent ${p}`);
   }
   logRenderedConflicts(tool, agentConflicts, true);
+  for (const p of automationPlan.write) {
+    console.log(`${tool}: would write automation ${p}`);
+  }
+  for (const p of automationPlan.remove) {
+    console.log(`${tool}: would remove automation ${p}`);
+  }
+  logRenderedConflicts(tool, automationConflicts, true);
   for (const p of globalDocsPlan.write) {
     console.log(`${tool}: would write global doc ${p}`);
   }
@@ -2620,6 +2966,8 @@ function logSyncDryRun({
     skillPlan.remove.length === 0 &&
     agentPlan.add.length === 0 &&
     agentPlan.remove.length === 0 &&
+    automationPlan.write.length === 0 &&
+    automationPlan.remove.length === 0 &&
     globalDocsPlan.write.length === 0 &&
     globalDocsPlan.remove.length === 0 &&
     rulesPlan.write.length === 0 &&
@@ -2628,6 +2976,7 @@ function logSyncDryRun({
     !configPlan.remove &&
     !mcpPlan.needsWrite &&
     agentConflicts.length === 0 &&
+    automationConflicts.length === 0 &&
     globalDocsConflicts.length === 0 &&
     rulesConflicts.length === 0 &&
     configConflicts.length === 0
@@ -2767,6 +3116,13 @@ async function syncManagedToolEntry({
         tool,
       })
     : { add: [], remove: [], contents: new Map(), sources: new Map() };
+  const automationPlan = entry.automationDir
+    ? await planAutomationFileChanges({
+        automationDir: entry.automationDir,
+        rootDir,
+        previouslyManagedTargets: Object.keys(entry.renderedTargets ?? {}),
+      })
+    : { add: [], remove: [], contents: new Map(), sources: new Map() };
 
   const mcpPlan = entry.mcpConfig
     ? await syncMcpConfig({
@@ -2846,6 +3202,15 @@ async function syncManagedToolEntry({
     desiredSources: globalDocsPlan.sources,
     conflictMode: builtinConflictMode,
   });
+  const automationRendered = await planRenderedTargetConflicts({
+    entry,
+    desiredWrites: automationPlan.add,
+    desiredRemoves: automationPlan.remove,
+    desiredContents: automationPlan.contents,
+    desiredSources: automationPlan.sources,
+    conflictMode: builtinConflictMode,
+    protectAllSources: true,
+  });
   const rulesRendered = await planRenderedTargetConflicts({
     entry,
     desiredWrites: rulesPlan.write,
@@ -2882,6 +3247,11 @@ async function syncManagedToolEntry({
       mcpPlan,
       agentPlan: { add: agentRendered.write, remove: agentRendered.remove },
       agentConflicts: agentRendered.conflicts,
+      automationPlan: {
+        write: automationRendered.write,
+        remove: automationRendered.remove,
+      },
+      automationConflicts: automationRendered.conflicts,
       globalDocsPlan: {
         write: globalDocsRendered.write,
         remove: globalDocsRendered.remove,
@@ -2902,6 +3272,14 @@ async function syncManagedToolEntry({
       contents: agentPlan.contents,
       targets: agentRendered.write,
     });
+    await applyRenderedRemoves(automationRendered.remove);
+    await applyRenderedWrites({
+      contents: automationPlan.contents,
+      targets: automationRendered.write,
+    });
+    if (entry.automationDir) {
+      await pruneEmptyParents(automationRendered.remove, entry.automationDir);
+    }
     await applyRenderedRemoves(globalDocsRendered.remove);
     await applyRenderedWrites({
       contents: globalDocsPlan.contents,
@@ -2918,6 +3296,7 @@ async function syncManagedToolEntry({
       targets: configRendered.write,
     });
     logRenderedConflicts(tool, agentRendered.conflicts);
+    logRenderedConflicts(tool, automationRendered.conflicts);
     logRenderedConflicts(tool, globalDocsRendered.conflicts);
     logRenderedConflicts(tool, rulesRendered.conflicts);
     logRenderedConflicts(tool, configRendered.conflicts);
@@ -2929,6 +3308,13 @@ async function syncManagedToolEntry({
       contents: agentPlan.contents,
       sources: agentPlan.sources,
     });
+    updateRenderedTargetState({
+      entry,
+      writtenTargets: automationRendered.write,
+      removedTargets: automationRendered.remove,
+      contents: automationPlan.contents,
+      sources: automationPlan.sources,
+    });
     updateRenderedTargetState({
       entry,
       writtenTargets: globalDocsRendered.write,

package/src/paths.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
@@ -93,6 +94,34 @@ export function preferredGlobalFacultStateDir(
   return join(preferredGlobalAiRoot(home), ".facult");
 }
 
+export function facultLocalStateRoot(home: string = defaultHomeDir()): string {
+  const override = process.env.FACULT_LOCAL_STATE_DIR?.trim();
+  if (override) {
+    return resolvePath(override, home);
+  }
+  if (process.platform === "darwin") {
+    return join(home, "Library", "Application Support", "fclt");
+  }
+  const xdg = process.env.XDG_STATE_HOME?.trim();
+  return xdg
+    ? join(resolvePath(xdg, home), "fclt")
+    : join(home, ".local", "state", "fclt");
+}
+
+export function facultLocalCacheRoot(home: string = defaultHomeDir()): string {
+  const override = process.env.FACULT_CACHE_DIR?.trim();
+  if (override) {
+    return resolvePath(override, home);
+  }
+  if (process.platform === "darwin") {
+    return join(home, "Library", "Caches", "fclt");
+  }
+  const xdg = process.env.XDG_CACHE_HOME?.trim();
+  return xdg
+    ? join(resolvePath(xdg, home), "fclt")
+    : join(home, ".cache", "fclt");
+}
+
 export function legacyExternalFacultStateDir(
   home: string = defaultHomeDir()
 ): string {
@@ -186,6 +215,46 @@ export function facultStateDir(
   return join(resolvedRoot, ".facult");
 }
 
+function machineStateProjectKey(
+  rootDir: string,
+  home: string = defaultHomeDir()
+): string {
+  const projectRoot = projectRootFromAiRoot(rootDir, home);
+  const labelSource = projectRoot ?? rootDir;
+  const label = basename(labelSource).trim().toLowerCase();
+  const slug = label.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  const digest = createHash("sha256")
+    .update(resolve(rootDir))
+    .digest("hex")
+    .slice(0, 12);
+  return `${slug || "project"}-${digest}`;
+}
+
+export function facultMachineStateDir(
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string {
+  const resolvedRoot = rootDir ?? facultRootDir(home);
+  const projectRoot = projectRootFromAiRoot(resolvedRoot, home);
+  return projectRoot
+    ? join(
+        facultLocalStateRoot(home),
+        "projects",
+        machineStateProjectKey(resolvedRoot, home)
+      )
+    : join(facultLocalStateRoot(home), "global");
+}
+
+export function facultInstallStatePath(
+  home: string = defaultHomeDir()
+): string {
+  return join(facultLocalStateRoot(home), "install.json");
+}
+
+export function facultRuntimeCacheDir(home: string = defaultHomeDir()): string {
+  return join(facultLocalCacheRoot(home), "runtime");
+}
+
 export function projectRootFromAiRoot(
   rootDir: string,
   home: string = defaultHomeDir()

package/src/self-update.ts

@@ -2,6 +2,7 @@ import { mkdir, rename } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import {
+  facultInstallStatePath,
   legacyExternalFacultStateDir,
   preferredGlobalFacultStateDir,
 } from "./paths";
@@ -88,6 +89,7 @@ export function parseSelfUpdateArgs(argv: string[]): ParsedArgs {
 
 async function loadInstallState(home: string): Promise<InstallState | null> {
   const paths = [
+    facultInstallStatePath(home),
     join(preferredGlobalFacultStateDir(home), "install.json"),
     join(legacyExternalFacultStateDir(home), "install.json"),
   ];
@@ -208,7 +210,7 @@ async function writeInstallState(args: {
   packageVersion?: string;
   binaryPath?: string;
 }) {
-  const dir = preferredGlobalFacultStateDir(args.home);
+  const dir = dirname(facultInstallStatePath(args.home));
   await mkdir(dir, { recursive: true });
   const payload: InstallState = {
     version: 1,
@@ -219,7 +221,7 @@ async function writeInstallState(args: {
     installedAt: new Date().toISOString(),
   };
   await Bun.write(
-    join(dir, "install.json"),
+    facultInstallStatePath(args.home),
     `${JSON.stringify(payload, null, 2)}\n`
   );
 }