facult 2.12.0 → 2.13.1

package/assets/packs/facult-operating-model/instructions/CAPABILITY_COMPOSITION.md

@@ -42,7 +42,7 @@ Use project scope for capability that belongs to a repo, team workflow, architec
 
 Promote project capability to global only when repeated evidence shows reuse across projects. Do not globalize a project quirk just because it worked once.
 
-## Writeback And Evolution
+## Writeback and Evolution
 
 Target the smallest affected unit.
 

package/assets/packs/facult-operating-model/instructions/EVOLUTION.md

@@ -98,7 +98,7 @@ Review surfaces:
 
 Evolution proposal metadata, markdown drafts, patch artifacts, writeback queues,
 and journals are runtime state. `fclt` stores JSON queues, proposal records,
-draft refs, patches, and journals in machine-local Facult state. It mirrors
+draft refs, patches, and journals in machine-local `fclt` state. It mirrors
 human-readable review artifacts into global `~/.ai/writebacks/...` and
 `~/.ai/evolution/...`, including project-scoped artifacts under
 `projects/<slug-hash>/` with cwd/project metadata in frontmatter. Canonical

package/assets/packs/facult-operating-model/instructions/LEARNING_AND_WRITEBACK.md

@@ -29,7 +29,7 @@ fclt ai writeback add --kind <kind> --summary "<summary>" --asset <asset-selecto
 ```
 
 The writeback queue is runtime state, not canonical source. `fclt` stores JSON
-queue state in machine-local Facult state so sandboxed agents can record durable
+queue state in machine-local `fclt` state so sandboxed agents can record durable
 friction without mutating canonical assets unless an evolution proposal is later
 reviewed and applied.
 

package/bin/fclt.cjs

@@ -15,6 +15,9 @@ const REPO_NAME = "fclt";
 const PACKAGE_NAME = "facult";
 const DOWNLOAD_RETRIES = 12;
 const DOWNLOAD_RETRY_DELAY_MS = 5000;
+const ACTIVE_RUNTIME_WAIT_MS = 10_000;
+const ACTIVE_RUNTIME_WAIT_INTERVAL_MS = 100;
+const STALE_RUNTIME_TEMP_MS = 10 * 60 * 1000;
 
 function isHelpLikeArgs(args) {
   return (
@@ -80,70 +83,75 @@ async function main() {
   let installedBinaryThisRun = false;
 
   if (!(await fileExists(binaryPath))) {
-    const packageManager = detectPackageManager();
-    const hasSourceFallback = await canUseSourceFallback(sourceEntry);
-    const incompleteCache = await hasIncompleteRuntimeCache({
+    await removeStaleRuntimeTemps({
       installDir,
       binaryName,
+      maxAgeMs: STALE_RUNTIME_TEMP_MS,
     });
+    const packageManager = detectPackageManager();
+    const hasSourceFallback = await canUseSourceFallback(sourceEntry);
 
-    if (incompleteCache) {
-      await removeIncompleteRuntimeTemps({ installDir, binaryName });
-    }
-
-    if (hasSourceFallback && (incompleteCache || isHelpLikeArgs(args))) {
+    if (hasSourceFallback && isHelpLikeArgs(args)) {
       return runSourceFallback({
         sourceEntry,
         version,
         packageManager,
-        reason: new Error(
-          incompleteCache
-            ? "incomplete cached runtime download"
-            : "runtime binary missing for help-like command"
-        ),
+        reason: new Error("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}`;
-    const tmpPath = `${binaryPath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
-
-    try {
-      await fsp.mkdir(installDir, { recursive: true });
-      await downloadWithRetry(url, tmpPath, {
-        attempts: DOWNLOAD_RETRIES,
-        delayMs: DOWNLOAD_RETRY_DELAY_MS,
+    if (await hasIncompleteRuntimeCache({ installDir, binaryName })) {
+      await waitForFile(binaryPath, {
+        timeoutMs: ACTIVE_RUNTIME_WAIT_MS,
+        intervalMs: ACTIVE_RUNTIME_WAIT_INTERVAL_MS,
       });
-      if (resolved.platform !== "windows") {
-        await fsp.chmod(tmpPath, 0o755);
-      }
-      await fsp.rename(tmpPath, binaryPath);
-      installedBinaryThisRun = true;
-    } catch (error) {
-      await safeUnlink(tmpPath);
-      if (await canUseSourceFallback(sourceEntry)) {
-        return runSourceFallback({
-          sourceEntry,
-          version,
-          packageManager: detectPackageManager(),
-          reason: error,
+    }
+
+    if (await fileExists(binaryPath)) {
+      // Another concurrent launcher finished the runtime install while this
+      // process was waiting.
+    } else {
+      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}`;
+      const tmpPath = `${binaryPath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+
+      try {
+        await fsp.mkdir(installDir, { recursive: true });
+        await downloadWithRetry(url, tmpPath, {
+          attempts: DOWNLOAD_RETRIES,
+          delayMs: DOWNLOAD_RETRY_DELAY_MS,
         });
+        if (resolved.platform !== "windows") {
+          await fsp.chmod(tmpPath, 0o755);
+        }
+        await installDownloadedRuntime(tmpPath, binaryPath);
+        installedBinaryThisRun = true;
+      } catch (error) {
+        await safeUnlink(tmpPath);
+        if (await canUseSourceFallback(sourceEntry)) {
+          return runSourceFallback({
+            sourceEntry,
+            version,
+            packageManager: detectPackageManager(),
+            reason: error,
+          });
+        }
+        const message =
+          error instanceof Error ? error.message : String(error ?? "");
+        console.error(
+          [
+            "Unable to download the fclt binary for this platform.",
+            `Expected asset: ${assetName}`,
+            `URL: ${url}`,
+            `Reason: ${message}`,
+            "",
+            "Try installing directly from releases:",
+            "https://github.com/hack-dance/fclt/releases",
+          ].join("\n")
+        );
+        process.exit(1);
       }
-      const message =
-        error instanceof Error ? error.message : String(error ?? "");
-      console.error(
-        [
-          "Unable to download the fclt binary for this platform.",
-          `Expected asset: ${assetName}`,
-          `URL: ${url}`,
-          `Reason: ${message}`,
-          "",
-          "Try installing directly from releases:",
-          "https://github.com/hack-dance/fclt/releases",
-        ].join("\n")
-      );
-      process.exit(1);
     }
   }
 
@@ -367,19 +375,58 @@ async function hasIncompleteRuntimeCache({ installDir, binaryName }) {
   }
 }
 
-async function removeIncompleteRuntimeTemps({ installDir, binaryName }) {
+async function removeStaleRuntimeTemps({ installDir, binaryName, maxAgeMs }) {
   try {
     const entries = await fsp.readdir(installDir);
-    await Promise.all(
-      entries
-        .filter((entry) => entry.startsWith(`${binaryName}.tmp-`))
-        .map((entry) => safeUnlink(path.join(installDir, entry)))
-    );
+    const now = Date.now();
+    const stalePaths = [];
+    for (const entry of entries) {
+      if (!entry.startsWith(`${binaryName}.tmp-`)) {
+        continue;
+      }
+      const candidate = path.join(installDir, entry);
+      try {
+        const stats = await fsp.stat(candidate);
+        if (now - stats.mtimeMs > maxAgeMs) {
+          stalePaths.push(candidate);
+        }
+      } catch {
+        // Ignore temp files that disappeared while scanning.
+      }
+    }
+    await Promise.all(stalePaths.map((candidate) => safeUnlink(candidate)));
   } catch {
     // Ignore missing runtime dirs while cleaning stale temp files.
   }
 }
 
+async function waitForFile(filePath, { timeoutMs, intervalMs }) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await fileExists(filePath)) {
+      return true;
+    }
+    await sleep(intervalMs);
+  }
+  return await fileExists(filePath);
+}
+
+async function installDownloadedRuntime(tmpPath, binaryPath) {
+  if (await fileExists(binaryPath)) {
+    await safeUnlink(tmpPath);
+    return;
+  }
+  try {
+    await fsp.rename(tmpPath, binaryPath);
+  } catch (error) {
+    if (await fileExists(binaryPath)) {
+      await safeUnlink(tmpPath);
+      return;
+    }
+    throw error;
+  }
+}
+
 async function safeUnlink(filePath) {
   try {
     await fsp.unlink(filePath);

package/docs/README.md

@@ -1,19 +1,29 @@
 # fclt Documentation
 
-These docs explain the product model behind `fclt`. The root [README](../README.md) is the quick start and command reference. The files here explain why the pieces exist and how they fit together.
+These docs explain how `fclt` stores, inspects, composes, renders, and improves AI capability.
 
-Start here:
+Start with the root [README](../README.md) for installation and first workflows. Use these guides when you need the model, safety rules, or command details.
+
+The concepts guide includes the [feedback-loop diagram](./assets/fclt-capability-loop.png) that explains why `fclt` exists: setup once, let agents preserve friction, then review the changes that should improve future work.
+
+## Guides
 
 - [Concepts](./concepts.md): canonical roots, generated state, rendered outputs, scopes, and asset types.
 - [Composable Capability](./composable-capability.md): refs, snippets, instruction templates, and evolvable units.
-- [Managed Mode](./managed-mode.md): when to let `fclt` write tool files, and how adoption works.
 - [Project `.ai`](./project-ai.md): how repo-local capability works without leaking project review state into the repo.
-- [Built-In Pack](./built-in-pack.md): the packaged operating-model layer for writeback and evolution.
-- [Writeback And Evolution](./writeback-evolution.md): how real-work friction becomes reviewable capability changes.
-- [Roadmap](./roadmap.md): current product gaps and non-goals.
+- [Built-in pack](./built-in-pack.md): the packaged operating-model layer for writeback and evolution.
+- [Writeback and evolution](./writeback-evolution.md): how real-work friction becomes reviewable capability changes.
+- [Managed mode](./managed-mode.md): when to let `fclt` write tool files, and how adoption works.
+- [Security and trust](./security-trust.md): source trust, audit, secrets, and commit hygiene.
+- [Automations](./automations.md): recurring Codex loops for learning review, evolution review, and tool-call audit.
+- [Command reference](./reference.md): command groups and common flags.
+- [Roadmap](./roadmap.md): current product gaps and planned work.
 
-## Documentation Policy
+## Reading Order
 
-Public docs should use generic examples. Do not include personal account names, private customer names, local machine paths, secret values, or project-specific operating notes. Use placeholders such as `/path/to/repo`, `example.com`, and `~/.ai`.
+New users should read:
 
-Machine-local state and review artifacts can contain project metadata. `fclt` keeps those artifacts in machine-local Facult state and global `~/.ai/writebacks` / `~/.ai/evolution` review directories, not in repo-local project `.ai` directories.
+- [Concepts](./concepts.md)
+- [Project `.ai`](./project-ai.md) if working in a repo
+- [Managed mode](./managed-mode.md) only before allowing `fclt` to write tool files
+- [Writeback and evolution](./writeback-evolution.md) before setting up feedback loops

package/docs/automations.md

@@ -0,0 +1,68 @@
+# Automations
+
+`fclt` can scaffold Codex automations that run the feedback loop on a schedule.
+
+Use automations for review and synthesis, not for bypassing review. They should preserve useful signal, group repeated patterns, and draft proposals only when the target is concrete.
+
+## Templates
+
+Learning review:
+
+```bash
+fclt templates init automation learning-review \
+  --scope project \
+  --project-root /path/to/repo \
+  --status PAUSED
+```
+
+Evolution review:
+
+```bash
+fclt templates init automation evolution-review \
+  --scope wide \
+  --cwds /path/to/repo-a,/path/to/repo-b \
+  --status PAUSED
+```
+
+Tool-call audit:
+
+```bash
+fclt templates init automation tool-call-audit \
+  --scope project \
+  --project-root /path/to/repo \
+  --status PAUSED
+```
+
+## Scopes
+
+- `project`: one repo. Use this for repo-specific writeback, verification, and tool friction.
+- `wide`: a small related set of repos. Use this for shared capability review.
+- `global`: global capability and shared agent behavior.
+
+Keep wide scopes intentionally small. A good automation should preserve source boundaries instead of mixing unrelated repos into one vague proposal.
+
+## Output
+
+Automation files are written to:
+
+```text
+~/.codex/automations/<name>/automation.toml
+~/.codex/automations/<name>/memory.md
+```
+
+When Codex is managed by `fclt`, canonical automation sources can live under:
+
+```text
+~/.ai/automations/<name>/
+<repo>/.ai/automations/<name>/
+```
+
+Project-scoped automation sources are default-deny for managed sync. Add their names to `[project_sync.codex].automations` before project managed sync can render them into the shared live Codex automation store.
+
+## Suggested Cadence
+
+- daily or per-project `learning-review` for durable signal
+- weekly `evolution-review` for proposal triage
+- targeted `tool-call-audit` when tool failures, missing skills, or shallow-success patterns repeat
+
+High-risk global changes should still move through proposal review before apply.

package/docs/built-in-pack.md

@@ -1,4 +1,4 @@
-# Built-In Pack
+# Built-in Pack
 
 `fclt` ships an operating-model pack:
 
@@ -6,7 +6,7 @@
 assets/packs/facult-operating-model/
 ```
 
-It provides a default feedback loop for agents that use `fclt`.
+It provides default guidance for agents that use `fclt`: define the work, verify it, record durable feedback, and turn repeated signal into reviewed changes.
 
 ## Included Assets
 
@@ -80,7 +80,7 @@ sync_defaults = false
 
 ## Design Rule
 
-The built-in pack should stay small. It should teach:
+The built-in pack should stay small. It teaches:
 
 - work-unit discipline
 - composable refs, snippets, instructions, skills, agents, MCP, and automations
@@ -90,4 +90,10 @@ The built-in pack should stay small. It should teach:
 - project/global scope decisions
 - managed-mode ownership boundaries
 
-It should not become a pile of preferences. Put project-specific behavior in project `.ai`; promote to global only when repeated evidence proves reuse.
+Keep project-specific behavior in project `.ai`. Promote it only when repeated evidence shows it is reusable outside that project.
+
+## Next
+
+- Read [Composable Capability](./composable-capability.md) for refs, snippets, and instruction templates.
+- Read [Writeback and evolution](./writeback-evolution.md) for the feedback loop.
+- Read [Managed mode](./managed-mode.md) before rendering the pack into a tool home.

package/docs/composable-capability.md

@@ -2,6 +2,8 @@
 
 `fclt` treats AI behavior as small capability units that can be composed into larger agent instructions and evolved independently.
 
+This prevents one giant agent file from becoming the only place to put every preference, workflow, and exception. A language preference can live in one instruction. A repeated rendered block can live in one snippet. A workflow can live in one skill. Each unit can receive targeted writeback and targeted evolution.
+
 This is the core model:
 
 - write domain guidance once
@@ -168,3 +170,9 @@ fclt ai evolve list
 ```
 
 Open `~/.ai/writebacks/` and `~/.ai/evolution/` in a markdown editor to inspect review artifacts with frontmatter status, scope, targets, project metadata, evidence, and proposal state.
+
+## Next
+
+- Read [Writeback and evolution](./writeback-evolution.md) for proposal flow.
+- Read [Built-in Pack](./built-in-pack.md) for packaged defaults.
+- Use [Command reference](./reference.md) for template and graph commands.

package/docs/concepts.md

@@ -4,6 +4,10 @@
 
 The important distinction is ownership. A file can be source, generated state, machine runtime state, a rendered output, or a review artifact. Treating those as separate layers prevents sync surprises.
 
+![fclt capability loop: setup, capability, agents, work units, writebacks, evolution, approval, and better future agents](./assets/fclt-capability-loop.png)
+
+The intended operating model is agent-led after setup. Users install and approve broad changes; agents inspect capability, run work units, record durable friction, and use repeated signal to propose small improvements.
+
 ## Roots And Scopes
 
 Global root:
@@ -66,7 +70,7 @@ Examples:
 ~/.ai/.facult/ai/graph.json
 ```
 
-Project generated state lives in machine-local Facult state, not in the repo.
+Project generated state lives in machine-local `fclt` state, not in the repo.
 
 Machine runtime state records local behavior and history.
 
@@ -123,3 +127,9 @@ The durable loop is:
 4. Draft the smallest valid proposal.
 5. Review and apply accepted changes to canonical source.
 6. Re-index and sync only the surfaces that should receive the change.
+
+## Next
+
+- Read [Project `.ai`](./project-ai.md) before adding repo-local capability.
+- Read [Managed mode](./managed-mode.md) before allowing `fclt` to write tool files.
+- Read [Composable Capability](./composable-capability.md) to split guidance into instructions, snippets, skills, agents, MCP, and automations.

package/docs/managed-mode.md

@@ -1,4 +1,4 @@
-# Managed Mode
+# Managed mode
 
 Managed mode is optional. Use it when you want `fclt` to write rendered files into a tool home. Do not use it just to inspect or normalize existing tool-native state.
 
@@ -37,9 +37,9 @@ When live content differs from canonical content:
 - rendered docs/config with local edits are skipped unless an explicit conflict option allows overwrite
 - built-in rendered defaults require `--builtin-conflicts overwrite` before replacing local edits
 
-This is deliberate. Managed mode should be boring and reversible.
+This is deliberate. Managed mode should be predictable and reversible.
 
-## Project Managed Mode
+## Project managed mode
 
 Project sync is default-deny. A project `.ai` root can exist without rendering anything into repo-local tool outputs.
 
@@ -60,7 +60,7 @@ tool_config = true
 
 If a repo-local `.ai` contains only generated state and no canonical assets, `fclt status --project` reports a generated-only warning and `fclt sync --project` skips. Initialize or restore canonical source before syncing managed project output.
 
-## When Not To Use Managed Mode
+## When not to use managed mode
 
 Do not use managed mode when:
 
@@ -71,3 +71,9 @@ Do not use managed mode when:
 - you are debugging and need read-only evidence first
 
 Use `fclt inventory`, `scan`, `list`, `show`, `graph`, `status`, and `audit` instead.
+
+## Next
+
+- Read [Project `.ai`](./project-ai.md) for repo-local sync policy.
+- Read [Security and trust](./security-trust.md) for MCP secrets and audit.
+- Use [Command reference](./reference.md) for common managed-mode commands.

package/docs/project-ai.md

@@ -1,6 +1,6 @@
 # Project `.ai`
 
-A project `.ai` root stores repo-owned capability. It is not a dumping ground for generated state, review queues, or private local context.
+A project `.ai` root stores repo-owned capability. It is for source that should travel with the codebase, not for generated state, review queues, or private local context.
 
 Create one with:
 
@@ -44,11 +44,11 @@ Do not put these in project `.ai`:
 - secrets
 - private review artifacts
 
-Project-scoped writebacks and evolution proposals are stored in machine-local Facult state and mirrored for review under global `~/.ai/writebacks/projects/<slug-hash>/` and `~/.ai/evolution/projects/<slug-hash>/`.
+Project-scoped writebacks and evolution proposals are stored in machine-local `fclt` state and mirrored for review under global `~/.ai/writebacks/projects/<slug-hash>/` and `~/.ai/evolution/projects/<slug-hash>/`.
 
-## Generated-Only Roots
+## Migration From Generated-Only Roots
 
-Older versions could leave `<repo>/.ai/.facult/ai/index.json` and `graph.json` behind without any canonical source. That makes the repo look like it has project AI state even though there is nothing durable to render.
+Some repos may contain `<repo>/.ai/.facult/ai/index.json` and `graph.json` without any canonical source. That makes the repo look like it has project AI state even though there is nothing durable to render.
 
 Current behavior:
 
@@ -79,6 +79,12 @@ tool_config = true
 
 This includes inherited global assets. If a global skill should appear in project-managed Codex output, list it explicitly.
 
+## Next
+
+- Read [Concepts](./concepts.md) for source, generated state, machine-local state, and rendered outputs.
+- Read [Managed mode](./managed-mode.md) before syncing project assets into tool outputs.
+- Read [Security and trust](./security-trust.md) before committing MCP config.
+
 ## Verification
 
 Use these commands after changing project `.ai`:

package/docs/reference.md

@@ -0,0 +1,112 @@
+# Command reference
+
+This page groups the main `fclt` commands by job. Use `fclt --help` and `fclt <command> --help` for exact flags.
+
+## Discovery
+
+```bash
+fclt status [--json]
+fclt doctor [--json] [--repair]
+fclt paths [--json]
+fclt scan [--from <path>] [--json] [--show-duplicates]
+fclt inventory [--json] [--tool <name>] [--show-secrets]
+fclt list [skills|mcp|agents|snippets|instructions|automations]
+fclt show <selector>
+fclt find <query>
+```
+
+Use these first. They let you inspect tool state without claiming ownership of any files.
+`doctor --json` is read-only and reports setup health, issues, and recommended
+actions. `paths --json` reports canonical, generated, runtime, and review paths
+for agents and integrations.
+
+## Graph
+
+```bash
+fclt graph show <selector>
+fclt graph deps <selector>
+fclt graph dependents <selector>
+```
+
+The graph explains how instructions, snippets, config refs, and rendered targets relate.
+
+## Canonical Store
+
+```bash
+fclt templates list
+fclt templates init operating-model [--global|--project|--root PATH]
+fclt templates init project-ai
+fclt templates init instruction <name>
+fclt templates init snippet <marker>
+fclt templates init skill <name>
+fclt templates init agent <name>
+fclt templates init mcp <name>
+fclt templates init automation <template-id> --scope global|project|wide
+fclt consolidate --auto keep-current --from <path>
+fclt index [--force]
+```
+
+Use these to create or normalize canonical capability in `~/.ai` or `<repo>/.ai`.
+
+## Managed mode
+
+```bash
+fclt manage <tool> [--dry-run] [--adopt-existing]
+fclt sync [tool] [--dry-run] [--adopt-live]
+fclt enable <selector> --for codex,claude
+fclt disable <selector> --for codex,claude
+fclt managed
+fclt unmanage <tool>
+```
+
+Managed mode writes rendered output into tool homes. Read [Managed mode](./managed-mode.md) before using it on an existing setup.
+
+## Writeback and evolution
+
+```bash
+fclt ai writeback add --kind <kind> --summary <text> --asset <selector>
+fclt ai writeback list
+fclt ai writeback show WB-00001
+fclt ai writeback group --by asset
+fclt ai writeback summarize --by kind
+
+fclt ai evolve propose
+fclt ai evolve list
+fclt ai evolve show EV-00001
+fclt ai evolve draft EV-00001
+fclt ai evolve review EV-00001
+fclt ai evolve accept EV-00001
+fclt ai evolve reject EV-00001 --reason <text>
+fclt ai evolve apply EV-00001
+fclt ai evolve promote EV-00003 --to global --project
+```
+
+Use these to turn repeated work friction into reviewed capability changes.
+
+## Sources, Audit, And Updates
+
+```bash
+fclt search <query>
+fclt install <source:item> [--as <name>] [--strict-source-trust]
+fclt update [--apply]
+fclt verify-source <name> [--json]
+fclt sources list
+fclt sources trust <source> [--note <text>]
+fclt sources review <source> [--note <text>]
+fclt sources block <source> [--note <text>]
+fclt sources clear <source>
+fclt audit [--non-interactive]
+fclt self-update
+```
+
+Use `--strict-source-trust` when installing or updating remote capability from catalogs.
+
+## Root Selection
+
+Most commands accept the same root controls:
+
+- `--global`: use `~/.ai`
+- `--project`: use the nearest repo-local `.ai`
+- `--root /path/to/.ai`: use an explicit canonical root
+- `--scope merged|global|project`: choose a discovery view
+- `--source builtin|global|project`: filter provenance in list/find/show/graph flows