facult 1.2.1 → 2.0.1

package/src/index.ts

@@ -96,50 +96,50 @@ interface GraphCommandOptions {
 }
 
 function printHelp() {
-  console.log(`facult — inspect local agent configs for skills + MCP servers
+  console.log(`fclt — manage canonical AI capabilities, sync surfaces, and evolution state
 
 Usage:
-  facult scan [--json] [--show-duplicates] [--tui] [--from <path>]
-  facult audit [--from <path>]
-  facult audit --non-interactive [name|mcp:<name>] [--severity <level>] [--rules <path>] [--from <path>] [--json]
-  facult audit --non-interactive [name|mcp:<name>] --with <claude|codex> [--from <path>] [--max-items <n|all>] [--json]
-  facult migrate [--from <path>] [--dry-run] [--move] [--write-config]
-  facult doctor [--repair]
-  facult consolidate [--force] [--auto <mode>] [scan options]
-  facult index [--force]
-  facult list [skills|mcp|agents|snippets|instructions] [--enabled-for TOOL] [--untrusted] [--flagged] [--pending] [--json]
-  facult show <name>
-  facult show mcp:<name> [--show-secrets]
-  facult show instruction:<name>
-  facult find <query> [--json]
-  facult graph <show|deps|dependents> <asset> [--json]
-  facult ai <writeback|evolve> [args...]
-  facult adapters
-  facult trust <name> [moreNames...]
-  facult untrust <name> [moreNames...]
-  facult manage <tool>
-  facult unmanage <tool>
-  facult managed
-  facult enable <name> [moreNames...] [--for <tools>]
-  facult disable <name> [moreNames...] [--for <tools>]
-  facult sync [tool] [--dry-run]
-  facult autosync <cmd> [args...]
-  facult search <query> [--index <name>] [--limit <n>]
-  facult install <index:item> [--as <name>] [--dry-run] [--force] [--strict-source-trust]
-  facult update [--apply] [--strict-source-trust]
-  facult update --self [--version <x.y.z|latest>] [--dry-run]
-  facult self-update [--version <x.y.z|latest>] [--dry-run]
-  facult verify-source <name> [--json]
-  facult sources <cmd> [args...]
-  facult templates <cmd> [args...]
-  facult snippets <cmd> [args...]
-  facult --show-duplicates
+  fclt scan [--json] [--show-duplicates] [--tui] [--from <path>]
+  fclt audit [--from <path>]
+  fclt audit --non-interactive [name|mcp:<name>] [--severity <level>] [--rules <path>] [--from <path>] [--json]
+  fclt audit --non-interactive [name|mcp:<name>] --with <claude|codex> [--from <path>] [--max-items <n|all>] [--json]
+  fclt migrate [--from <path>] [--dry-run] [--move] [--write-config]
+  fclt doctor [--repair]
+  fclt consolidate [--force] [--auto <mode>] [scan options]
+  fclt index [--force]
+  fclt list [skills|mcp|agents|snippets|instructions] [--enabled-for TOOL] [--untrusted] [--flagged] [--pending] [--json]
+  fclt show <name>
+  fclt show mcp:<name> [--show-secrets]
+  fclt show instruction:<name>
+  fclt find <query> [--json]
+  fclt graph <show|deps|dependents> <asset> [--json]
+  fclt ai <writeback|evolve> [args...]
+  fclt adapters
+  fclt trust <name> [moreNames...]
+  fclt untrust <name> [moreNames...]
+  fclt manage <tool>
+  fclt unmanage <tool>
+  fclt managed
+  fclt enable <name> [moreNames...] [--for <tools>]
+  fclt disable <name> [moreNames...] [--for <tools>]
+  fclt sync [tool] [--dry-run]
+  fclt autosync <cmd> [args...]
+  fclt search <query> [--index <name>] [--limit <n>]
+  fclt install <index:item> [--as <name>] [--dry-run] [--force] [--strict-source-trust]
+  fclt update [--apply] [--strict-source-trust]
+  fclt update --self [--version <x.y.z|latest>] [--dry-run]
+  fclt self-update [--version <x.y.z|latest>] [--dry-run]
+  fclt verify-source <name> [--json]
+  fclt sources <cmd> [args...]
+  fclt templates <cmd> [args...]
+  fclt snippets <cmd> [args...]
+  fclt --show-duplicates
 
 Commands:
   scan         Scan common config locations (Cursor, Claude, Claude Desktop, etc.)
   audit        Security audits (interactive by default; use --non-interactive for scripts)
   migrate      Copy/move a legacy canonical store to the current canonical root
-  doctor       Inspect and repair local facult state
+  doctor       Inspect and repair local fclt state
   consolidate  Deduplicate and copy skills + MCP configs (interactive or --auto)
   index        Build a queryable index from the canonical store (see FACULT_ROOT_DIR)
   list         List indexed skills, MCP servers, agents, snippets, or instructions
@@ -160,7 +160,7 @@ Commands:
   search       Search remote indices (builtin + provider aliases + configured)
   install      Install an item from a remote index
   update       Check/apply updates for remotely installed items
-  self-update  Update facult itself based on install method
+  self-update  Update fclt itself based on install method
   verify-source  Verify source trust and manifest integrity/signature status
   sources      Manage source trust policy for remote indices
   templates    Scaffold DX-first templates (skills/instructions/MCP/snippets)
@@ -177,7 +177,7 @@ Options:
   --from-max-results  (scan) Max discovered paths per --from root before truncating
   --non-interactive   (audit) Run static/agent audit non-interactively (for scripts)
   --severity          Minimum severity to include in audit output (low|medium|high|critical)
-  --rules             Path to an audit rules YAML file (default: ~/.facult/audit-rules.yaml)
+  --rules             Path to an audit rules YAML file (default: ~/.ai/.facult/audit-rules.yaml)
   --with              (audit) Agent tool: claude|codex
   --max-items         (audit) Max items to send to the agent (n|all)
   --force             Re-copy items already consolidated OR rebuild index from scratch
@@ -203,10 +203,10 @@ Options:
 }
 
 function printListHelp() {
-  console.log(`facult list — list indexed entries from the canonical store
+  console.log(`fclt list — list indexed entries from the canonical store
 
 Usage:
-  facult list [skills|mcp|agents|snippets|instructions] [options]
+  fclt list [skills|mcp|agents|snippets|instructions] [options]
 
 Options:
   --enabled-for TOOL  Only include entries enabled for a tool
@@ -223,12 +223,12 @@ Options:
 }
 
 function printShowHelp() {
-  console.log(`facult show — show a single indexed entry (and file contents)
+  console.log(`fclt show — show a single indexed entry (and file contents)
 
 Usage:
-  facult show <name>
-  facult show mcp:<name> [--show-secrets]
-  facult show instruction:<name>
+  fclt show <name>
+  fclt show mcp:<name> [--show-secrets]
+  fclt show instruction:<name>
 
 Options:
   --show-secrets      (mcp) Print raw secret values (unsafe)
@@ -241,10 +241,10 @@ Options:
 }
 
 function printFindHelp() {
-  console.log(`facult find — search local indexed capabilities across asset types
+  console.log(`fclt find — search local indexed capabilities across asset types
 
 Usage:
-  facult find <query> [--json]
+  fclt find <query> [--json]
 
 Options:
   --root PATH         Select a canonical .ai root explicitly
@@ -257,12 +257,12 @@ Options:
 }
 
 function printGraphHelp() {
-  console.log(`facult graph — inspect explicit capability graph nodes and relations
+  console.log(`fclt graph — inspect explicit capability graph nodes and relations
 
 Usage:
-  facult graph show <asset> [--json]
-  facult graph deps <asset> [--json]
-  facult graph dependents <asset> [--json]
+  fclt graph show <asset> [--json]
+  fclt graph deps <asset> [--json]
+  fclt graph dependents <asset> [--json]
 
 Options:
   --root PATH         Select a canonical .ai root explicitly
@@ -890,7 +890,7 @@ async function graphCommand(argv: string[]) {
 function adaptersCommand(argv: string[]) {
   if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
     console.log(
-      "facult adapters — list registered tool adapters\n\nUsage:\n  facult adapters\n"
+      "fclt adapters — list registered tool adapters\n\nUsage:\n  fclt adapters\n"
     );
     return;
   }
@@ -912,7 +912,7 @@ async function main(argv: string[]) {
     return;
   }
 
-  // Convenience: allow `facult --show-duplicates` as shorthand for `facult scan --show-duplicates`.
+  // Convenience: allow `fclt --show-duplicates` as shorthand for `fclt scan --show-duplicates`.
   if (cmd === "--show-duplicates") {
     await scanCommand([cmd, ...rest]);
     return;

package/src/manage.ts

@@ -34,6 +34,7 @@ import {
 import {
   facultGeneratedStateDir,
   facultRootDir,
+  legacyFacultStateDirForRoot,
   projectRootFromAiRoot,
 } from "./paths";
 
@@ -295,22 +296,37 @@ export function managedStatePathForRoot(
   return join(facultGeneratedStateDir({ home, rootDir }), "managed.json");
 }
 
+function legacyManagedStatePathForRoot(
+  home: string = homedir(),
+  rootDir?: string
+): string {
+  return join(
+    legacyFacultStateDirForRoot(rootDir ?? facultRootDir(home), home),
+    "managed.json"
+  );
+}
+
 export async function loadManagedState(
   home: string = homedir(),
   rootDir?: string
 ): Promise<ManagedState> {
-  const p = managedStatePathForRoot(home, rootDir);
-  if (!(await fileExists(p))) {
-    return { version: MANAGED_VERSION, tools: {} };
-  }
-  try {
-    const txt = await Bun.file(p).text();
-    const data = JSON.parse(txt) as Partial<ManagedState> | null;
-    if (data?.version === MANAGED_VERSION && data.tools) {
-      return { version: MANAGED_VERSION, tools: data.tools };
+  const candidates = [
+    managedStatePathForRoot(home, rootDir),
+    legacyManagedStatePathForRoot(home, rootDir),
+  ];
+  for (const p of candidates) {
+    if (!(await fileExists(p))) {
+      continue;
+    }
+    try {
+      const txt = await Bun.file(p).text();
+      const data = JSON.parse(txt) as Partial<ManagedState> | null;
+      if (data?.version === MANAGED_VERSION && data.tools) {
+        return { version: MANAGED_VERSION, tools: data.tools };
+      }
+    } catch {
+      // fallthrough
     }
-  } catch {
-    // fallthrough
   }
   return { version: MANAGED_VERSION, tools: {} };
 }
@@ -1830,7 +1846,7 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
             .map((item) => formatManagedItem(item))
             .join(", ")}`
         : null,
-      `Run "facult manage ${tool} --dry-run" to review the plan, then rerun with "--adopt-existing"`,
+      `Run "fclt manage ${tool} --dry-run" to review the plan, then rerun with "--adopt-existing"`,
       existingImportPlan.conflicts.length > 0
         ? ' and "--existing-conflicts keep-canonical|keep-existing".'
         : ".",
@@ -3001,10 +3017,10 @@ export async function manageCommand(argv: string[]) {
   const parsed = parseCliContextArgs(argv);
   const args = [...parsed.argv];
   if (args.includes("--help") || args.includes("-h") || args[0] === "help") {
-    console.log(`facult manage — enter managed mode for a tool (backup + symlinks + MCP generation)
+    console.log(`fclt manage — enter managed mode for a tool (backup + symlinks + MCP generation)
 
 Usage:
-  facult manage <tool> [--dry-run] [--adopt-existing] [--existing-conflicts keep-canonical|keep-existing] [--builtin-conflicts overwrite] [--root PATH|--global|--project]
+  fclt manage <tool> [--dry-run] [--adopt-existing] [--existing-conflicts keep-canonical|keep-existing] [--builtin-conflicts overwrite] [--root PATH|--global|--project]
 `);
     return;
   }
@@ -3089,10 +3105,10 @@ export async function unmanageCommand(argv: string[]) {
     parsed.argv.includes("-h") ||
     parsed.argv[0] === "help"
   ) {
-    console.log(`facult unmanage — exit managed mode for a tool (restore backups)
+    console.log(`fclt unmanage — exit managed mode for a tool (restore backups)
 
 Usage:
-  facult unmanage <tool> [--root PATH|--global|--project]
+  fclt unmanage <tool> [--root PATH|--global|--project]
 `);
     return;
   }
@@ -3124,10 +3140,10 @@ export async function managedCommand(argv: string[] = []) {
     parsed.argv.includes("-h") ||
     parsed.argv[0] === "help"
   ) {
-    console.log(`facult managed — list tools currently in managed mode
+    console.log(`fclt managed — list tools currently in managed mode
 
 Usage:
-  facult managed [--root PATH|--global|--project]
+  fclt managed [--root PATH|--global|--project]
 `);
     return;
   }
@@ -3154,10 +3170,10 @@ export async function syncCommand(argv: string[]) {
     parsed.argv.includes("-h") ||
     parsed.argv[0] === "help"
   ) {
-    console.log(`facult sync — sync managed tools with canonical state
+    console.log(`fclt sync — sync managed tools with canonical state
 
 Usage:
-  facult sync [tool] [--dry-run] [--builtin-conflicts overwrite] [--root PATH|--global|--project]
+  fclt sync [tool] [--dry-run] [--builtin-conflicts overwrite] [--root PATH|--global|--project]
 
 Options:
   --dry-run   Show what would change

package/src/migrate.ts

@@ -11,23 +11,24 @@ import {
 } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
+import { facultConfigPath, preferredGlobalAiRoot } from "./paths";
 
 function printHelp() {
-  console.log(`facult migrate — migrate a legacy canonical store to the facult path
+  console.log(`fclt migrate — migrate a legacy canonical store to the fclt path
 
 Usage:
-  facult migrate [--from <path>] [--dry-run] [--move] [--write-config]
+  fclt migrate [--from <path>] [--dry-run] [--move] [--write-config]
 
 What it does:
   - Auto-detects a legacy store under ~/agents/ (or use --from)
-  - Copies it to ~/agents/.facult (default, safe)
+  - Copies it to ~/.ai (default, safe)
   - Or moves it with --move (destructive; removes the legacy directory)
 
 Options:
   --from           Path to a legacy store root directory
   --dry-run        Print what would happen without changing anything
   --move           Rename legacy dir to the new location instead of copying
-  --write-config   Write ~/.facult/config.json to pin rootDir to ~/agents/.facult
+  --write-config   Write ~/.ai/.facult/config.json to pin rootDir to ~/.ai
 `);
 }
 
@@ -188,9 +189,8 @@ export async function migrateCommand(argv: string[]) {
   const writeConfig = argv.includes("--write-config");
 
   const home = homedir();
-  const dest = join(home, "agents", ".facult");
-  const stateDir = join(home, ".facult");
-  const configPath = join(stateDir, "config.json");
+  const dest = preferredGlobalAiRoot(home);
+  const configPath = facultConfigPath(home);
 
   let legacy: string | null = null;
   try {
@@ -239,7 +239,7 @@ export async function migrateCommand(argv: string[]) {
       return;
     }
     console.error(
-      `Destination exists but does not look like a facult store: ${dest}`
+      `Destination exists but does not look like a fclt store: ${dest}`
     );
     process.exitCode = 1;
     return;
@@ -264,7 +264,7 @@ export async function migrateCommand(argv: string[]) {
     if (dryRun) {
       console.log(`[dry-run] Would write ${configPath} with rootDir=${dest}`);
     } else {
-      await mkdir(stateDir, { recursive: true });
+      await mkdir(dirname(configPath), { recursive: true });
       await Bun.write(configPath, JSON.stringify({ rootDir: dest }, null, 2));
       console.log(`Wrote ${configPath}`);
     }

package/src/paths.ts

@@ -7,13 +7,13 @@ export interface FacultConfig {
   /**
    * Override the canonical root directory.
    *
-   * This is where facult stores the consolidated "canonical" skill + MCP state
+   * This is where fclt stores the consolidated "canonical" skill + MCP state
    * (skills/, mcp/, snippets/, index.json, ...).
    */
   rootDir?: string;
 
   /**
-   * Default scan roots (equivalent to passing `facult scan --from <path>`).
+   * Default scan roots (equivalent to passing `fclt scan --from <path>`).
    * Example: ["~", "~/dev", "~/work"]
    */
   scanFrom?: string[];
@@ -83,6 +83,22 @@ function legacyPreferredRoot(home: string): string {
   return join(home, "agents", ".facult");
 }
 
+export function preferredGlobalAiRoot(home: string = defaultHomeDir()): string {
+  return join(home, ".ai");
+}
+
+export function preferredGlobalFacultStateDir(
+  home: string = defaultHomeDir()
+): string {
+  return join(preferredGlobalAiRoot(home), ".facult");
+}
+
+export function legacyExternalFacultStateDir(
+  home: string = defaultHomeDir()
+): string {
+  return join(home, ".facult");
+}
+
 function isLegacyConfiguredRoot(root: string, home: string): boolean {
   return resolve(root) === resolve(legacyPreferredRoot(home));
 }
@@ -91,7 +107,7 @@ function looksLikeFacultRoot(root: string): boolean {
   if (!dirExists(root)) {
     return false;
   }
-  // Heuristic: treat as a facult store if it contains something we'd create.
+  // Heuristic: treat as a fclt store if it contains something we'd create.
   return (
     dirExists(join(root, "rules")) ||
     dirExists(join(root, "instructions")) ||
@@ -132,8 +148,42 @@ function detectLegacyStoreUnderAgents(home: string): string | null {
   return candidates.length === 1 ? (candidates[0] ?? null) : null;
 }
 
-export function facultStateDir(home: string = defaultHomeDir()): string {
-  return join(home, ".facult");
+export function legacyFacultStateDirForRoot(
+  rootDir: string,
+  home: string = defaultHomeDir()
+): string {
+  const projectRoot = projectRootFromAiRoot(rootDir, home);
+  return projectRoot
+    ? join(projectRoot, ".facult")
+    : legacyExternalFacultStateDir(home);
+}
+
+function shouldUsePreferredGlobalStateDir(
+  rootDir: string,
+  home: string
+): boolean {
+  const resolved = resolve(rootDir);
+  if (projectRootFromAiRoot(resolved, home)) {
+    return false;
+  }
+  if (resolved === resolve(preferredGlobalAiRoot(home))) {
+    return true;
+  }
+  if (resolved === resolve(legacyPreferredRoot(home))) {
+    return true;
+  }
+  return resolved.startsWith(`${resolve(join(home, "agents"))}/`);
+}
+
+export function facultStateDir(
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string {
+  const resolvedRoot = rootDir ?? facultRootDir(home);
+  if (shouldUsePreferredGlobalStateDir(resolvedRoot, home)) {
+    return preferredGlobalFacultStateDir(home);
+  }
+  return join(resolvedRoot, ".facult");
 }
 
 export function projectRootFromAiRoot(
@@ -168,9 +218,7 @@ export function facultGeneratedStateDir(args?: {
   rootDir?: string;
 }): string {
   const home = args?.home ?? defaultHomeDir();
-  const rootDir = args?.rootDir;
-  const projectRoot = rootDir ? projectRootFromAiRoot(rootDir, home) : null;
-  return projectRoot ? join(projectRoot, ".facult") : facultStateDir(home);
+  return facultStateDir(home, args?.rootDir);
 }
 
 export function facultAiStateDir(
@@ -198,10 +246,12 @@ export function facultAiRuntimeScopeDir(
   home: string = defaultHomeDir(),
   rootDir?: string
 ): string {
-  const slug = rootDir ? projectSlugFromAiRoot(rootDir, home) : null;
-  return slug
-    ? join(facultStateDir(home), "ai", "projects", slug)
-    : join(facultStateDir(home), "ai", "global");
+  return join(
+    facultAiStateDir(home, rootDir),
+    projectRootFromAiRoot(rootDir ?? facultRootDir(home), home)
+      ? "project"
+      : "global"
+  );
 }
 
 export function facultAiJournalPath(
@@ -241,87 +291,95 @@ export function facultAiDraftDir(
 }
 
 export function facultConfigPath(home: string = defaultHomeDir()): string {
-  return join(facultStateDir(home), "config.json");
+  return join(preferredGlobalFacultStateDir(home), "config.json");
 }
 
 export function readFacultConfig(
   home: string = defaultHomeDir()
 ): FacultConfig | null {
-  const p = facultConfigPath(home);
-  if (!(isSafePathString(p) && fileExists(p))) {
-    return null;
-  }
+  const candidates = [
+    facultConfigPath(home),
+    join(legacyExternalFacultStateDir(home), "config.json"),
+  ];
 
-  try {
-    const txt = readFileSync(p, "utf8");
-    const parsed = parseJsonLenient(txt) as unknown;
-    if (!isPlainObject(parsed)) {
-      return null;
+  for (const p of candidates) {
+    if (!(isSafePathString(p) && fileExists(p))) {
+      continue;
     }
-    const rootDir =
-      typeof parsed.rootDir === "string" ? parsed.rootDir : undefined;
-
-    const scanFromRaw = (parsed as Record<string, unknown>).scanFrom;
-    const scanFrom = Array.isArray(scanFromRaw)
-      ? scanFromRaw
-          .filter((v) => typeof v === "string")
-          .map((v) => v.trim())
-          .filter(Boolean)
-      : undefined;
-
-    const scanFromIgnoreRaw = (parsed as Record<string, unknown>)
-      .scanFromIgnore;
-    const scanFromIgnore = Array.isArray(scanFromIgnoreRaw)
-      ? scanFromIgnoreRaw
-          .filter((v) => typeof v === "string")
-          .map((v) => v.trim())
-          .filter(Boolean)
-      : undefined;
-
-    const scanFromNoDefaultIgnore =
-      typeof (parsed as Record<string, unknown>).scanFromNoDefaultIgnore ===
-      "boolean"
-        ? ((parsed as Record<string, unknown>)
-            .scanFromNoDefaultIgnore as boolean)
-        : undefined;
 
-    const scanFromMaxVisitsRaw = (parsed as Record<string, unknown>)
-      .scanFromMaxVisits;
-    const scanFromMaxVisits =
-      typeof scanFromMaxVisitsRaw === "number" &&
-      Number.isFinite(scanFromMaxVisitsRaw) &&
-      scanFromMaxVisitsRaw > 0
-        ? Math.floor(scanFromMaxVisitsRaw)
+    try {
+      const txt = readFileSync(p, "utf8");
+      const parsed = parseJsonLenient(txt) as unknown;
+      if (!isPlainObject(parsed)) {
+        continue;
+      }
+      const rootDir =
+        typeof parsed.rootDir === "string" ? parsed.rootDir : undefined;
+
+      const scanFromRaw = (parsed as Record<string, unknown>).scanFrom;
+      const scanFrom = Array.isArray(scanFromRaw)
+        ? scanFromRaw
+            .filter((v) => typeof v === "string")
+            .map((v) => v.trim())
+            .filter(Boolean)
         : undefined;
 
-    const scanFromMaxResultsRaw = (parsed as Record<string, unknown>)
-      .scanFromMaxResults;
-    const scanFromMaxResults =
-      typeof scanFromMaxResultsRaw === "number" &&
-      Number.isFinite(scanFromMaxResultsRaw) &&
-      scanFromMaxResultsRaw > 0
-        ? Math.floor(scanFromMaxResultsRaw)
+      const scanFromIgnoreRaw = (parsed as Record<string, unknown>)
+        .scanFromIgnore;
+      const scanFromIgnore = Array.isArray(scanFromIgnoreRaw)
+        ? scanFromIgnoreRaw
+            .filter((v) => typeof v === "string")
+            .map((v) => v.trim())
+            .filter(Boolean)
         : undefined;
 
-    return {
-      rootDir,
-      scanFrom,
-      scanFromIgnore,
-      scanFromNoDefaultIgnore,
-      scanFromMaxVisits,
-      scanFromMaxResults,
-    };
-  } catch {
-    return null;
+      const scanFromNoDefaultIgnore =
+        typeof (parsed as Record<string, unknown>).scanFromNoDefaultIgnore ===
+        "boolean"
+          ? ((parsed as Record<string, unknown>)
+              .scanFromNoDefaultIgnore as boolean)
+          : undefined;
+
+      const scanFromMaxVisitsRaw = (parsed as Record<string, unknown>)
+        .scanFromMaxVisits;
+      const scanFromMaxVisits =
+        typeof scanFromMaxVisitsRaw === "number" &&
+        Number.isFinite(scanFromMaxVisitsRaw) &&
+        scanFromMaxVisitsRaw > 0
+          ? Math.floor(scanFromMaxVisitsRaw)
+          : undefined;
+
+      const scanFromMaxResultsRaw = (parsed as Record<string, unknown>)
+        .scanFromMaxResults;
+      const scanFromMaxResults =
+        typeof scanFromMaxResultsRaw === "number" &&
+        Number.isFinite(scanFromMaxResultsRaw) &&
+        scanFromMaxResultsRaw > 0
+          ? Math.floor(scanFromMaxResultsRaw)
+          : undefined;
+
+      return {
+        rootDir,
+        scanFrom,
+        scanFromIgnore,
+        scanFromNoDefaultIgnore,
+        scanFromMaxVisits,
+        scanFromMaxResults,
+      };
+    } catch {
+      // Ignore invalid config files and continue to the next fallback path.
+    }
   }
+
+  return null;
 }
 
 /**
- * Return the canonical facult root directory.
+ * Return the canonical fclt root directory.
  *
  * Precedence:
  * 1) `FACULT_ROOT_DIR` env var
- * 2) `~/.facult/config.json` { "rootDir": "..." }
+ * 2) `~/.ai/.facult/config.json` { "rootDir": "..." } (falls back to legacy `~/.facult/config.json`)
  * 3) `~/.ai` (if it looks like a store)
  * 4) `~/agents/.facult` (if it looks like a store)
  * 5) a legacy store under `~/agents/` (if it looks like a store)

package/src/quarantine.ts

@@ -12,6 +12,7 @@ import {
 } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
+import { facultStateDir } from "./paths";
 
 export type QuarantineMode = "move" | "copy";
 
@@ -157,7 +158,7 @@ export async function quarantineItems(args: {
   const ts = args.timestamp ?? new Date().toISOString();
   const stamp = ts.replace(/[:.]/g, "-");
   const quarantineDir =
-    args.destDir ?? join(home, ".facult", "quarantine", stamp);
+    args.destDir ?? join(facultStateDir(home), "quarantine", stamp);
 
   const entries: QuarantineEntry[] = [];