facult 1.0.2 → 1.1.0

package/README.md

@@ -1,12 +1,28 @@
 # facult
 
-`facult` is a CLI for managing coding-agent skills and MCP configs across tools.
+<div align="center">
+  <a aria-label="NPM version" href="https://www.npmjs.com/package/facult">
+    <img alt="facult npm version" src="https://img.shields.io/npm/v/facult.svg?style=flat-square&logo=npm&labelColor=000000&label=facult">
+  </a>
+  <a aria-label="CI status" href="https://github.com/hack-dance/facult/actions/workflows/ci.yml">
+    <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/hack-dance/facult/ci.yml?branch=main&style=flat-square&logo=github&label=ci&labelColor=000000">
+  </a>
+  <a aria-label="hack.dance" href="https://hack.dance">
+    <img alt="Made by hack.dance" src="https://img.shields.io/badge/MADE%20BY%20HACK.DANCE-000000.svg?style=flat-square&labelColor=000000">
+  </a>
+  <a aria-label="X" href="https://x.com/dimitrikennedy">
+    <img alt="Follow on X" src="https://img.shields.io/twitter/follow/dimitrikennedy?style=social">
+  </a>
+</div>
+
+`facult` is a CLI for managing coding-agent configuration across tools.
 
 It helps you:
 - discover what is installed on your machine
 - consolidate everything into one canonical store
 - review trust/security before installing remote content
-- enable a curated skill set across Codex, Cursor, and Claude
+- sync managed outputs into Codex, Cursor, and Claude
+- manage a git-backed personal AI store under `~/.ai`
 
 ## What facult Is
 
@@ -16,6 +32,7 @@ Think of it as:
 - inventory + auditing for agent assets
 - package manager interface for skill/MCP catalogs
 - sync layer that applies your chosen setup to each tool
+- canonical source manager for global AI instructions, agents, snippets, tool configs, and rules
 
 ## Quick Start
 
@@ -43,12 +60,6 @@ Direct binary install from GitHub Releases (macOS/Linux):
 curl -fsSL https://github.com/hack-dance/facult/releases/latest/download/facult-install.sh | bash
 ```
 
-If release assets are private, set a token first:
-
-```bash
-export FACULT_GITHUB_TOKEN="<github-token>"
-```
-
 Windows and manual installs can download the correct binary from each release page:
 `facult-<version>-<platform>-<arch>`.
 
@@ -66,7 +77,17 @@ Pin to a specific version:
 facult self-update --version 0.0.1
 ```
 
-### 2. Import existing skills/configs
+### 2. Start with a read-only inventory (recommended first)
+
+```bash
+facult scan --show-duplicates
+# optional machine-readable output
+facult scan --json
+```
+
+`scan` is read-only. It inspects local configs and reports what `facult` found without changing files.
+
+### 3. Import existing skills/configs
 
 ```bash
 facult consolidate --auto keep-current --from ~/.codex/skills --from ~/.agents/skills
@@ -75,9 +96,9 @@ facult index
 
 Why `keep-current`: it is deterministic and non-interactive for duplicate sources.
 
-Default canonical store: `~/agents/.facult`. You can change it later with `FACULT_ROOT_DIR` or `~/.facult/config.json`.
+Canonical source root: `~/.ai`. Generated state remains under `~/.facult`.
 
-### 3. Inspect what you have
+### 4. Inspect what you have
 
 ```bash
 facult list skills
@@ -86,7 +107,7 @@ facult show requesting-code-review
 facult show mcp:github
 ```
 
-### 4. Enable managed mode for your tools
+### 5. Enable managed mode for your tools
 
 ```bash
 facult manage codex
@@ -99,7 +120,21 @@ facult sync
 
 At this point, your selected skills are actively synced to all managed tools.
 
-### 5. Turn on source trust and strict install flow
+### 6. Turn on background autosync
+
+```bash
+facult autosync install --git-remote origin --git-branch main --git-interval-minutes 60
+facult autosync status
+```
+
+This installs a per-user macOS LaunchAgent that:
+- watches `~/.ai` for local changes and syncs managed tool outputs automatically
+- tracks dirty state for the canonical repo
+- runs a slower git autosync loop that batches changes, auto-commits them, rebases on the configured remote branch, and pushes on success
+
+If the repo hits a rebase conflict, remote autosync stops and reports the blocked state, but local tool sync continues.
+
+### 7. Turn on source trust and strict install flow
 
 ```bash
 facult sources list
@@ -140,6 +175,94 @@ facult sync
 
 Note: `templates init mcp ...` is a scaffold, not a running server by itself.
 
+## The `~/.ai` Model
+
+`facult` now treats `~/.ai` as the canonical, git-backed source of truth for personal AI configuration.
+
+Typical layout:
+
+```text
+~/.ai/
+  AGENTS.global.md
+  AGENTS.override.global.md
+  config.toml
+  config.local.toml
+  instructions/
+  snippets/
+  agents/
+  skills/
+  mcp/
+  templates/
+  tools/
+    codex/
+      config.toml
+      rules/
+  projects/
+    <slug>/
+      config.toml
+      config.local.toml
+      snippets/
+      instructions/
+```
+
+Important split:
+- `~/.ai` is canonical source
+- `~/.facult` is generated state, trust state, managed tool state, autosync state, and caches
+- tool homes such as `~/.codex` are rendered outputs
+
+### Canonical conventions
+
+- Use `instructions/` for reusable markdown documents
+- Use `snippets/` for composable partial blocks injected into markdown templates
+- Use `tools/codex/rules/*.rules` for actual Codex approval-policy rules
+- Use logical refs such as `@ai/instructions/WRITING.md` in tracked source
+- Use config-backed refs in prompts where you want stable named references such as `${refs.writing_rule}`
+
+### Config and env layering
+
+Canonical render context is layered explicitly:
+1. built-ins injected by `facult`
+2. `~/.ai/config.toml`
+3. `~/.ai/config.local.toml`
+4. `~/.ai/projects/<slug>/config.toml`
+5. `~/.ai/projects/<slug>/config.local.toml`
+6. explicit runtime overrides
+
+Built-ins currently include:
+- `AI_ROOT`
+- `HOME`
+- `PROJECT_ROOT`
+- `PROJECT_SLUG`
+- `TARGET_TOOL`
+- `TARGET_PATH`
+
+Recommended split:
+- `config.toml`: tracked, portable, non-secret refs/defaults
+- `config.local.toml`: ignored, machine-local paths and secrets
+
+### Snippets
+
+Snippets use HTML comment markers:
+
+```md
+<!-- fclty:global/codex/baseline -->
+<!-- /fclty:global/codex/baseline -->
+```
+
+Resolution rules:
+- unscoped marker `codingstyle` prefers `snippets/projects/<project>/codingstyle.md`, then falls back to `snippets/global/codingstyle.md`
+- explicit marker `global/codex/baseline` resolves directly to `snippets/global/codex/baseline.md`
+
+Commands:
+
+```bash
+facult snippets list
+facult snippets show global/codex/baseline
+facult snippets sync [--dry-run] [file...]
+```
+
+Snippets are already used during global Codex `AGENTS.md` rendering.
+
 ## Security and Trust
 
 `facult` has two trust layers:
@@ -174,10 +297,11 @@ Recommended security flow:
 ### Capability categories
 
 - Inventory: discover local skills, MCP configs, hooks, and instruction files
-- Management: consolidate, index, manage/unmanage tools, enable/disable entries
+- Management: consolidate, index, manage/unmanage tools, enable/disable entries, manage canonical AI config
 - Security: static audit, agent audit, item trust, source trust, source verification
 - Distribution: search/install/update from catalogs and verified manifests
 - DX: scaffold templates and sync snippets into instruction/config files
+- Automation: background autosync for local tool propagation and canonical repo git sync
 
 ### Command categories
 
@@ -205,6 +329,10 @@ facult enable <name> [--for <tool1,tool2,...>]
 facult enable mcp:<name> [--for <tool1,tool2,...>]
 facult disable <name> [--for <tool1,tool2,...>]
 facult sync [tool] [--dry-run]
+facult autosync install [tool] [--git-remote <name>] [--git-branch <name>] [--git-interval-minutes <n>] [--git-disable]
+facult autosync status [tool]
+facult autosync restart [tool]
+facult autosync uninstall [tool]
 ```
 
 - Remote catalogs and policies
@@ -247,13 +375,12 @@ facult <command> --help
 `facult` resolves the canonical root in this order:
 1. `FACULT_ROOT_DIR`
 2. `~/.facult/config.json` (`rootDir`)
-3. `~/agents/.facult` (or a detected legacy store under `~/agents/`)
+3. `~/.ai`
+4. `~/agents/.facult` (or a detected legacy store under `~/agents/`)
 
 ### Runtime env vars
 
 - `FACULT_ROOT_DIR`: override canonical store location
-- `FACULT_GITHUB_TOKEN`: auth token for private GitHub release asset downloads
-- `GITHUB_TOKEN` / `GH_TOKEN`: fallback tokens for release asset downloads
 - `FACULT_VERSION`: version selector for `scripts/install.sh` (`latest` by default)
 - `FACULT_INSTALL_DIR`: install target dir for `scripts/install.sh` (`~/.facult/bin` by default)
 - `FACULT_INSTALL_PM`: force package manager detection for npm bootstrap launcher (`npm` or `bun`)
@@ -264,9 +391,13 @@ Under `~/.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)
 
 ### Config reference
 
@@ -283,7 +414,7 @@ Under `~/.facult/`:
 Example:
 ```json
 {
-  "rootDir": "~/agents/.facult",
+  "rootDir": "~/.ai",
   "scanFrom": ["~/dev", "~/work"],
   "scanFromIgnore": ["vendor", ".venv"],
   "scanFromNoDefaultIgnore": false,
@@ -315,6 +446,42 @@ bun run install:status
 
 Default install path is `~/.facult/bin/facult`. You can pass a custom target dir via `--dir=/path`.
 
+## Autosync
+
+`facult autosync` is the background propagation layer for managed installs.
+
+Current v1 behavior:
+- macOS LaunchAgent-backed
+- immediate local managed-tool sync on `~/.ai` file changes
+- periodic git autosync for the canonical repo
+- automatic autosync commits with source-tagged commit messages such as:
+  - `chore(facult-autosync): sync canonical ai changes from <host> [service:all]`
+
+Recommended usage:
+
+```bash
+facult autosync install
+facult autosync status
+```
+
+Tool-scoped service:
+
+```bash
+facult autosync install codex
+```
+
+One-shot runner for verification/debugging:
+
+```bash
+facult autosync run --service all --once
+```
+
+Remote git policy:
+- do not sync on every file event
+- mark the canonical repo dirty on local changes
+- on the configured timer, fetch, auto-commit local canonical changes if needed, pull `--rebase`, then push
+- if rebase conflicts occur, remote autosync is blocked and reported, but local managed-tool sync keeps running
+
 ## CI and Release Automation
 
 - CI workflow: `.github/workflows/ci.yml`
@@ -381,3 +548,18 @@ bun run release:dry-run
 Not as a first-party `facult mcp serve` runtime.
 
 `facult` currently focuses on inventory, trust/audit, install/update, and managed sync of skills/MCP configs.
+
+### Does facult now manage global AI config, not just skills and MCP?
+
+Yes. The core model now includes:
+- canonical personal AI source in `~/.ai`
+- rendered managed outputs in tool homes such as `~/.codex`
+- global instruction docs such as `AGENTS.global.md`
+- tool-native configs such as `~/.codex/config.toml`
+- tool-native rule files such as `~/.codex/rules/*.rules`
+
+### Do I still need to run `facult sync` manually?
+
+If autosync is not installed, yes.
+
+If autosync is installed, local changes under `~/.ai` propagate automatically to managed tools. Manual `facult sync` is still useful for explicit repair, dry-runs, and non-daemon workflows.

package/bin/facult.cjs

@@ -37,7 +37,6 @@ async function main() {
   );
   const binaryName = resolved.platform === "windows" ? "facult.exe" : "facult";
   const binaryPath = path.join(installDir, binaryName);
-  const githubToken = resolveGitHubToken();
 
   if (!(await fileExists(binaryPath))) {
     const tag = `v${version}`;
@@ -50,7 +49,6 @@ async function main() {
       await downloadWithRetry(url, tmpPath, {
         attempts: DOWNLOAD_RETRIES,
         delayMs: DOWNLOAD_RETRY_DELAY_MS,
-        token: githubToken,
       });
       if (resolved.platform !== "windows") {
         await fsp.chmod(tmpPath, 0o755);
@@ -149,48 +147,19 @@ function detectPackageManager() {
   return "npm";
 }
 
-function resolveGitHubToken() {
-  const tokenCandidates = [
-    process.env.FACULT_GITHUB_TOKEN,
-    process.env.GITHUB_TOKEN,
-    process.env.GH_TOKEN,
-  ];
-  for (const candidate of tokenCandidates) {
-    const token = String(candidate || "").trim();
-    if (token) {
-      return token;
-    }
-  }
-  return "";
-}
-
-function buildRequestHeaders(url, token) {
-  const headers = {
+function buildRequestHeaders() {
+  return {
     "user-agent": "facult-installer",
     accept: "application/octet-stream",
   };
-  if (!token) {
-    return headers;
-  }
-
-  try {
-    const hostname = new URL(url).hostname.toLowerCase();
-    if (hostname === "github.com" || hostname === "api.github.com") {
-      headers.authorization = `Bearer ${token}`;
-    }
-  } catch {
-    // Keep default headers if URL parsing fails.
-  }
-
-  return headers;
 }
 
-async function download(url, destinationPath, options = {}) {
+async function download(url, destinationPath) {
   await new Promise((resolve, reject) => {
     const request = https.get(
       url,
       {
-        headers: buildRequestHeaders(url, options.token),
+        headers: buildRequestHeaders(),
       },
       (response) => {
         if (
@@ -200,7 +169,7 @@ async function download(url, destinationPath, options = {}) {
           response.headers.location
         ) {
           response.resume();
-          download(response.headers.location, destinationPath, options)
+          download(response.headers.location, destinationPath)
             .then(resolve)
             .catch(reject);
           return;
@@ -240,7 +209,7 @@ async function downloadWithRetry(url, destinationPath, options) {
   for (let attempt = 1; attempt <= options.attempts; attempt += 1) {
     try {
       await safeUnlink(destinationPath);
-      await download(url, destinationPath, { token: options.token });
+      await download(url, destinationPath);
       return;
     } catch (error) {
       lastError = error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Manage coding-agent skills and MCP configs across tools.",
   "type": "module",
   "license": "MIT",

package/src/adapters/codex.ts

@@ -11,6 +11,7 @@ export const codexAdapter: ToolAdapter = {
   getDefaultPaths: () => ({
     mcp: "~/.codex/mcp.json",
     skills: "~/.codex/skills",
+    agents: "~/.codex/agents",
     config: "~/.config/openai/codex.json",
   }),
   parseMcp: (config) => parseMcpConfig(config),

package/src/adapters/types.ts

@@ -21,6 +21,7 @@ export interface CanonicalSkill {
 export interface AdapterDefaultPaths {
   mcp?: string;
   skills?: string | string[];
+  agents?: string | string[];
   config?: string;
 }
 

package/src/agents.ts

@@ -0,0 +1,180 @@
+import { join } from "node:path";
+
+const AI_REF_RE = /(?<![\w@])@ai\/([^\s"'`<>]+)/g;
+const INTERPOLATION_RE = /\$\{([^}]+)\}/g;
+const TRAILING_PUNCTUATION_RE = /[.,;:!?)}\]]+$/;
+const MAX_RENDER_PASSES = 10;
+
+export interface RenderCanonicalTextOptions {
+  homeDir?: string;
+  rootDir: string;
+  projectSlug?: string;
+  projectRoot?: string;
+  targetTool?: string;
+  targetPath?: string;
+  overrides?: Record<string, unknown>;
+}
+
+type RenderContext = Record<string, unknown>;
+
+function trimTrailingPunctuation(refPath: string): {
+  path: string;
+  suffix: string;
+} {
+  const match = TRAILING_PUNCTUATION_RE.exec(refPath);
+  if (!match) {
+    return { path: refPath, suffix: "" };
+  }
+
+  const suffix = match[0];
+  return {
+    path: refPath.slice(0, -suffix.length),
+    suffix,
+  };
+}
+
+export function renderAiRefs(input: string, canonicalRoot: string): string {
+  return input.replace(AI_REF_RE, (_match, refPath: string) => {
+    const { path, suffix } = trimTrailingPunctuation(refPath);
+    return `${join(canonicalRoot, path)}${suffix}`;
+  });
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function mergeContexts(
+  base: Record<string, unknown>,
+  override: Record<string, unknown>
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...base };
+
+  for (const [key, value] of Object.entries(override)) {
+    const current = merged[key];
+    if (isPlainObject(current) && isPlainObject(value)) {
+      merged[key] = mergeContexts(current, value);
+      continue;
+    }
+    merged[key] = value;
+  }
+
+  return merged;
+}
+
+async function readTomlFile(
+  pathValue: string
+): Promise<Record<string, unknown> | null> {
+  const file = Bun.file(pathValue);
+  if (!(await file.exists())) {
+    return null;
+  }
+
+  const text = await file.text();
+  const parsed = Bun.TOML.parse(text);
+  return isPlainObject(parsed) ? parsed : null;
+}
+
+function getContextValue(
+  context: Record<string, unknown>,
+  dottedPath: string
+): unknown {
+  const segments = dottedPath
+    .split(".")
+    .map((segment) => segment.trim())
+    .filter(Boolean);
+  if (segments.length === 0) {
+    return undefined;
+  }
+
+  let current: unknown = context;
+  for (const segment of segments) {
+    if (!(isPlainObject(current) && segment in current)) {
+      return undefined;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+
+function interpolateString(
+  input: string,
+  context: Record<string, unknown>
+): string {
+  return input.replace(INTERPOLATION_RE, (match, keyPath: string) => {
+    const value = getContextValue(context, keyPath.trim());
+    return typeof value === "string" ? value : match;
+  });
+}
+
+export async function loadRenderContext(
+  options: RenderCanonicalTextOptions
+): Promise<RenderContext> {
+  const {
+    homeDir,
+    overrides,
+    projectRoot,
+    projectSlug,
+    rootDir,
+    targetPath,
+    targetTool,
+  } = options;
+  const contextBase: RenderContext = {
+    AI_ROOT: rootDir,
+    HOME: homeDir ?? "",
+    PROJECT_ROOT: projectRoot ?? "",
+    PROJECT_SLUG: projectSlug ?? "",
+    TARGET_PATH: targetPath ?? "",
+    TARGET_TOOL: targetTool ?? "",
+  };
+
+  let context = contextBase;
+  const layers = [
+    await readTomlFile(join(rootDir, "config.toml")),
+    await readTomlFile(join(rootDir, "config.local.toml")),
+    projectSlug
+      ? await readTomlFile(
+          join(rootDir, "projects", projectSlug, "config.toml")
+        )
+      : null,
+    projectSlug
+      ? await readTomlFile(
+          join(rootDir, "projects", projectSlug, "config.local.toml")
+        )
+      : null,
+    overrides && isPlainObject(overrides) ? overrides : null,
+  ];
+
+  for (const layer of layers) {
+    if (layer) {
+      context = mergeContexts(context, layer);
+    }
+  }
+
+  return context;
+}
+
+export async function renderCanonicalText(
+  input: string,
+  options: RenderCanonicalTextOptions
+): Promise<string> {
+  const context = await loadRenderContext(options);
+  let rendered = input;
+  const seen = new Set<string>();
+
+  for (let pass = 0; pass < MAX_RENDER_PASSES; pass += 1) {
+    if (seen.has(rendered)) {
+      break;
+    }
+    seen.add(rendered);
+
+    const interpolated = interpolateString(rendered, context);
+    const withRefs = renderAiRefs(interpolated, options.rootDir);
+    if (withRefs === rendered) {
+      return withRefs;
+    }
+    rendered = withRefs;
+  }
+
+  return rendered;
+}

package/src/ai-state.ts

@@ -0,0 +1,55 @@
+import { copyFile, mkdir, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { buildIndex } from "./index-builder";
+import { facultAiIndexPath } from "./paths";
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function legacyAiIndexPath(rootDir: string): string {
+  return join(rootDir, "index.json");
+}
+
+export async function ensureAiIndexPath(args: {
+  homeDir: string;
+  rootDir: string;
+  repair?: boolean;
+}): Promise<{
+  path: string;
+  repaired: boolean;
+  source: "generated" | "legacy" | "rebuilt" | "missing";
+}> {
+  const generatedPath = facultAiIndexPath(args.homeDir);
+  if (await fileExists(generatedPath)) {
+    return { path: generatedPath, repaired: false, source: "generated" };
+  }
+
+  const legacyPath = legacyAiIndexPath(args.rootDir);
+  if (await fileExists(legacyPath)) {
+    if (args.repair !== false) {
+      await mkdir(dirname(generatedPath), { recursive: true });
+      await copyFile(legacyPath, generatedPath);
+    }
+    return {
+      path: generatedPath,
+      repaired: args.repair !== false,
+      source: "legacy",
+    };
+  }
+
+  if (args.repair !== false) {
+    const { outputPath } = await buildIndex({
+      rootDir: args.rootDir,
+      homeDir: args.homeDir,
+      force: false,
+    });
+    return { path: outputPath, repaired: true, source: "rebuilt" };
+  }
+
+  return { path: generatedPath, repaired: false, source: "missing" };
+}