facult 2.9.0 → 2.10.0

package/README.md

@@ -127,7 +127,7 @@ fclt index
 
 Why `keep-current`: it is deterministic and non-interactive for duplicate sources.
 
-### 4. Manage a tool and sync
+### 4. Optional: manage a tool and sync
 
 ```bash
 fclt manage codex --dry-run
@@ -140,7 +140,11 @@ fclt enable requesting-code-review receiving-code-review brainstorming systemati
 fclt sync
 ```
 
-Use `--dry-run` first if the live tool already has local content. If the tool already contains skills, agents, rules, docs, config, or MCP definitions, rerun with `--adopt-existing` and add `--existing-conflicts keep-canonical|keep-existing` if names collide.
+Managed rendering is an advanced mode. Prefer `fclt inventory`, `fclt list`, `fclt consolidate`, and explicit writeback/evolution when you mainly want visibility and normalization across Codex, Claude, and other tool homes. Use `manage` only when you want fclt to write rendered files back into a tool.
+
+Use `--dry-run` first if the live tool already has local content. If the tool already contains skills, agents, rules, docs, config, or MCP definitions, rerun `manage` with `--adopt-existing` and add `--existing-conflicts keep-canonical|keep-existing` if names collide.
+
+Ordinary `fclt sync` does not import live tool edits into canonical state. If you intentionally edited skills, agents, docs, rules, config, or MCP entries in Codex/Claude and want fclt to pick them up, run `fclt sync --adopt-live`.
 
 Codex path policy:
 - skills render to `.agents/skills`
@@ -200,6 +204,8 @@ Useful AI behavior is composable. You need small reusable parts, a clean way to
 - discovery and graph views for dependencies, provenance, and rendered targets
 - writeback and evolution flows for improving canonical assets over time
 
+The renderer is optional. The low-friction default is to let tools keep their native files, use `fclt inventory`/`scan`/`list` to see the full global set, and use `fclt consolidate` or `fclt sync --adopt-live` only when you explicitly want to promote live tool edits into canonical `~/.ai`.
+
 ## Built-in Defaults
 
 `fclt` includes a built-in layer for writeback and evolution. By default, that layer provides:
@@ -231,9 +237,10 @@ Put that in `config.toml` or `config.local.toml` under the active canonical root
 
 `fclt` is CLI-first. The practical setup is:
 1. Install `fclt` globally so any agent runtime can execute it.
-2. Manage each agent tool with `fclt manage <tool>` and `fclt sync`.
-3. Let the built-in operating-model layer render global writeback/evolution instructions into the tool.
-4. Optionally scaffold MCP wrappers if you want an MCP entry that delegates to `fclt`.
+2. Use `fclt inventory`, `fclt list`, and `fclt consolidate` to inspect and normalize existing tool-native state.
+3. If you want fclt-owned rendered outputs, manage each agent tool with `fclt manage <tool>` and `fclt sync`.
+4. Let the built-in operating-model layer render global writeback/evolution instructions into the tool only where managed rendering is worth the ownership tradeoff.
+5. Optionally scaffold MCP wrappers if you want an MCP entry that delegates to `fclt`.
 
 ```bash
 # Scaffold reusable templates in the canonical store
@@ -592,7 +599,7 @@ fclt disable <name> [--for <tool1,tool2,...>]
 fclt trust --all
 fclt trust skills --all
 fclt untrust mcp --all
-fclt sync [tool] [--dry-run] [--builtin-conflicts overwrite]
+fclt sync [tool] [--dry-run] [--adopt-live] [--builtin-conflicts overwrite]
 fclt autosync install [tool] [--git-remote <name>] [--git-branch <name>] [--git-interval-minutes <n>] [--git-disable]
 fclt autosync status [tool]
 fclt autosync restart [tool]

package/package.json

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

package/src/manage.ts

@@ -137,6 +137,7 @@ export interface SyncOptions {
   tool?: string;
   dryRun?: boolean;
   builtinConflictMode?: "warn" | "overwrite";
+  adoptLive?: boolean;
 }
 
 const MANAGED_VERSION = 1 as const;
@@ -2421,12 +2422,14 @@ async function syncSkillSymlinks({
   rootDir,
   tool,
   dryRun,
+  adoptLive,
 }: {
   homeDir: string;
   toolSkillsDir: string;
   rootDir: string;
   tool: string;
   dryRun?: boolean;
+  adoptLive?: boolean;
 }): Promise<SkillSymlinkPlan> {
   const plan = await planSkillSymlinkChanges({
     homeDir,
@@ -2438,10 +2441,12 @@ async function syncSkillSymlinks({
     return plan;
   }
 
-  const adoptedConflicts = await adoptSkillSymlinkConflictsIntoCanonical({
-    rootDir,
-    conflicts: plan.conflicts,
-  });
+  const adoptedConflicts = adoptLive
+    ? await adoptSkillSymlinkConflictsIntoCanonical({
+        rootDir,
+        conflicts: plan.conflicts,
+      })
+    : [];
   const adoptedNames = new Set(
     adoptedConflicts.map((conflict) => conflict.name)
   );
@@ -3646,7 +3651,8 @@ function logRenderedConflicts(
 function logSkillSymlinkConflicts(
   tool: string,
   conflicts: SkillSymlinkConflict[],
-  dryRun?: boolean
+  dryRun?: boolean,
+  mode: "adopt" | "skip" = "skip"
 ) {
   for (const conflict of conflicts) {
     const verb =
@@ -3654,9 +3660,13 @@ function logSkillSymlinkConflicts(
         ? dryRun
           ? "would preserve"
           : "preserved"
-        : dryRun
-          ? "would adopt"
-          : "adopted";
+        : mode === "adopt"
+          ? dryRun
+            ? "would adopt"
+            : "adopted"
+          : dryRun
+            ? "would skip"
+            : "skipped";
     const state =
       conflict.reason === "unmanaged"
         ? "it is not in canonical skill state"
@@ -3667,7 +3677,7 @@ function logSkillSymlinkConflicts(
       ? ` (canonical ${conflict.canonicalPath})`
       : "";
     console.warn(
-      `${tool}: ${verb} skill ${conflict.name} from ${conflict.livePath}${canonical} because ${state}.`
+      `${tool}: ${verb} skill ${conflict.name} from ${conflict.livePath}${canonical} because ${state}.${mode === "skip" && conflict.reason !== "disabled" ? ' Rerun with "--adopt-live" to import it into canonical state.' : ""}`
     );
   }
 }
@@ -4470,6 +4480,7 @@ async function syncManagedToolEntry({
   rootDir,
   dryRun,
   builtinConflictMode,
+  adoptLive,
 }: {
   homeDir: string;
   tool: string;
@@ -4477,6 +4488,7 @@ async function syncManagedToolEntry({
   rootDir: string;
   dryRun?: boolean;
   builtinConflictMode?: "warn" | "overwrite";
+  adoptLive?: boolean;
 }) {
   const correlationId = randomUUID();
   const baseLedger = syncLedgerBase({
@@ -4515,14 +4527,15 @@ async function syncManagedToolEntry({
     automationDir: entry.automationDir,
   });
 
-  const adoptedSkills = dryRun
-    ? []
-    : await repairManagedCanonicalContent({
-        homeDir,
-        rootDir,
-        tool,
-        entry,
-      });
+  const adoptedSkills =
+    dryRun || !adoptLive
+      ? []
+      : await repairManagedCanonicalContent({
+          homeDir,
+          rootDir,
+          tool,
+          entry,
+        });
 
   const skillPlan = entry.skillsDir
     ? await syncSkillSymlinks({
@@ -4531,6 +4544,7 @@ async function syncManagedToolEntry({
         rootDir,
         tool,
         dryRun,
+        adoptLive,
       })
     : { add: [], remove: [], conflicts: [], adopted: [] };
   const skillLedgerEvents = collectSkillLedgerEvents({
@@ -4895,8 +4909,8 @@ async function syncManagedToolEntry({
     logRenderedConflicts(tool, configRendered.conflicts);
     logRenderedConflicts(tool, mcpRendered.conflicts);
     logRenderedConflicts(tool, pluginRendered.conflicts);
-    logSkillSymlinkConflicts(tool, skillPlan.adopted);
-    logSkillSymlinkConflicts(tool, skillPlan.conflicts);
+    logSkillSymlinkConflicts(tool, skillPlan.adopted, false, "adopt");
+    logSkillSymlinkConflicts(tool, skillPlan.conflicts, false, "skip");
 
     updateRenderedTargetState({
       entry,
@@ -5004,6 +5018,7 @@ export async function syncManagedTools(opts: SyncOptions = {}) {
       rootDir,
       dryRun: opts.dryRun,
       builtinConflictMode: opts.builtinConflictMode,
+      adoptLive: opts.adoptLive,
     });
   }
 
@@ -5196,16 +5211,20 @@ export async function syncCommand(argv: string[]) {
     console.log(`fclt sync — sync managed tools with canonical state
 
 Usage:
-  fclt sync [tool] [--dry-run] [--builtin-conflicts overwrite] [--root PATH|--global|--project]
+  fclt sync [tool] [--dry-run] [--adopt-live] [--builtin-conflicts overwrite] [--root PATH|--global|--project]
 
 Options:
   --dry-run   Show what would change
+  --adopt-live   Import live tool content into canonical state before rendering
   --builtin-conflicts overwrite   Replace locally modified builtin-backed rendered files
 `);
     return;
   }
   const tool = parsed.argv.find((arg) => !arg.startsWith("-"));
   const dryRun = parsed.argv.includes("--dry-run");
+  const adoptLive =
+    parsed.argv.includes("--adopt-live") ||
+    parsed.argv.includes("--adopt-live-skills");
   const builtinConflictIndex = parsed.argv.indexOf("--builtin-conflicts");
   let builtinConflictMode: "warn" | "overwrite" | undefined;
   if (builtinConflictIndex !== -1) {
@@ -5221,6 +5240,7 @@ Options:
     await syncManagedTools({
       tool,
       dryRun,
+      adoptLive,
       builtinConflictMode,
       rootDir: resolveCliContextRoot({
         rootArg: parsed.rootArg,