{"id":47595875,"url":"https://github.com/hack-dance/fclt","last_synced_at":"2026-04-01T18:04:47.675Z","repository":{"id":339836413,"uuid":"1142570546","full_name":"hack-dance/fclt","owner":"hack-dance","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-30T20:45:07.000Z","size":28920,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T21:23:57.965Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hack-dance.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-26T15:28:05.000Z","updated_at":"2026-03-30T20:45:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hack-dance/fclt","commit_stats":null,"previous_names":["hack-dance/facult","hack-dance/fclt"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/hack-dance/fclt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hack-dance%2Ffclt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hack-dance%2Ffclt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hack-dance%2Ffclt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hack-dance%2Ffclt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hack-dance","download_url":"https://codeload.github.com/hack-dance/fclt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hack-dance%2Ffclt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-01T18:04:21.652Z","updated_at":"2026-04-01T18:04:47.664Z","avatar_url":"https://github.com/hack-dance.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fclt\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca aria-label=\"NPM version\" href=\"https://www.npmjs.com/package/facult\"\u003e\n    \u003cimg alt=\"facult npm version\" src=\"https://img.shields.io/npm/v/facult.svg?style=flat-square\u0026logo=npm\u0026labelColor=000000\u0026label=facult\"\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"Homebrew tap\" href=\"https://github.com/hack-dance/homebrew-tap\"\u003e\n    \u003cimg alt=\"Homebrew tap\" src=\"https://img.shields.io/badge/homebrew-hack--dance%2Ftap%2Ffclt-FBB040.svg?style=flat-square\u0026logo=homebrew\u0026logoColor=white\u0026labelColor=000000\"\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"CI status\" href=\"https://github.com/hack-dance/fclt/actions/workflows/ci.yml\"\u003e\n    \u003cimg alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/hack-dance/fclt/ci.yml?branch=main\u0026style=flat-square\u0026logo=github\u0026label=ci\u0026labelColor=000000\"\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"hack.dance\" href=\"https://hack.dance\"\u003e\n    \u003cimg alt=\"Made by hack.dance\" src=\"https://img.shields.io/badge/MADE%20BY%20HACK.DANCE-000000.svg?style=flat-square\u0026labelColor=000000\"\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"X\" href=\"https://x.com/dimitrikennedy\"\u003e\n    \u003cimg alt=\"Follow on X\" src=\"https://img.shields.io/twitter/follow/dimitrikennedy?style=social\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"fclt demo\" src=\"./Ghostty.gif\"\u003e\n\u003c/p\u003e\n\n`fclt` is a CLI for building and evolving AI faculties across tools, users, and projects.\n\n`fclt` manages the reusable parts of your AI setup: instructions, snippets, templates, skills, agents, rules, and the feedback loops that improve them over time.\n\nIt helps you:\n- keep a canonical store in `~/.ai` or `\u003crepo\u003e/.ai`\n- render managed tool files into Codex, Claude, Cursor, and similar tools\n- inspect dependencies, provenance, and rendered outputs\n- review trust and audit remote or local capability before it spreads\n- capture writebacks and evolve canonical assets over time\n\n## Quick Start\n\n### 1. Install fclt\n\nRecommended global install:\n\n```bash\nbrew tap hack-dance/tap\nbrew install hack-dance/tap/fclt\nfclt --help\n```\n\nPackage-manager install:\n\n```bash\nnpm install -g facult\n# or\nbun add -g facult\nfclt --help\n```\n\nThe npm package name stays `facult` for registry compatibility. The installed command is still `fclt`.\n\nOne-off usage without global install:\n\n```bash\nnpx --yes -p facult fclt --help\n```\n\nDirect binary install from GitHub Releases (macOS/Linux):\n\n```bash\ncurl -fsSL https://github.com/hack-dance/fclt/releases/latest/download/fclt-install.sh | bash\n```\n\nWindows and manual installs can download the correct binary from each release page:\n`fclt-\u003cversion\u003e-\u003cplatform\u003e-\u003carch\u003e`.\n\nUpdate later with:\n\n```bash\nfclt self-update\n# or\nfclt update --self\n```\n\nPin to a specific version:\n\n```bash\nfclt self-update --version 0.0.1\n```\n\n### 2. Scan or bootstrap your canonical store\n\n```bash\nfclt scan --show-duplicates\n```\n\n`scan` is read-only. It inspects local configs and reports what `fclt` found without changing files.\n\nIf you want a repo-local `.ai`:\n\n```bash\ncd /path/to/repo\nfclt templates init project-ai\nfclt index\n```\n\n### 3. Import existing skills or config\n\n```bash\nfclt consolidate --auto keep-current --from ~/.codex/skills --from ~/.agents/skills\nfclt index\n```\n\nWhy `keep-current`: it is deterministic and non-interactive for duplicate sources.\n\n### 4. Manage a tool and sync\n\n```bash\nfclt manage codex --dry-run\nfclt manage codex --adopt-existing\nfclt sync codex --builtin-conflicts overwrite\nfclt manage cursor\nfclt manage claude\n\nfclt enable requesting-code-review receiving-code-review brainstorming systematic-debugging --for codex,cursor,claude\nfclt sync\n```\n\nUse `--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.\n\nCodex path policy:\n- skills render to `.agents/skills`\n- local plugin marketplaces render to `.agents/plugins/marketplace.json`\n- local plugin bundles render to `plugins/`\n- Codex runtime config, rules, agents, and automations still render under `.codex/`\n\nIf you run these commands inside a repo that has `\u003crepo\u003e/.ai`, `fclt` targets the project-local canonical store and repo-local tool outputs by default.\n\n### 5. Inspect and evolve\n\n```bash\nfclt list skills\nfclt show instruction:WRITING\nfclt show mcp:github\nfclt find verification\nfclt graph AGENTS.global.md\nfclt ai writeback add --kind weak_verification --summary \"Checks were too shallow\" --asset instruction:VERIFICATION\nfclt ai evolve propose\n```\n\nContext controls:\n\n```bash\nfclt list instructions --global\nfclt list instructions --project\nfclt find verification --scope merged --source project\nfclt list agents --root /path/to/repo/.ai\n```\n\n### 6. Optional: autosync, source trust, and audit\n\n```bash\nfclt autosync install --git-remote origin --git-branch main --git-interval-minutes 60\nfclt autosync status\n\nfclt sources list\nfclt verify-source skills.sh --json\nfclt sources trust skills.sh --note \"reviewed\"\nfclt install skills.sh:code-review --as code-review-skills-sh --strict-source-trust\n\nfclt audit\nfclt audit --non-interactive --severity high\nfclt audit safe mcp:github --rule static:mcp-env-inline-secret --note \"reviewed\"\nfclt audit fix mcp:github\n```\n\n## Overview\n\nUseful AI behavior is composable. You need small reusable parts, a clean way to combine them, and a safe way to render them into the files your tools actually use.\n\n`fclt` is a canonical store plus a renderer:\n- canonical store in `~/.ai` or `\u003crepo\u003e/.ai`\n- rendered tool files in places like `~/.codex`, `~/.claude`, or repo-local tool dirs\n- discovery and graph views for dependencies, provenance, and rendered targets\n- writeback and evolution flows for improving canonical assets over time\n\n## Built-in Defaults\n\n`fclt` includes a built-in layer for writeback and evolution. By default, that layer provides:\n- instructions for evolution, integration, and project capability\n- agents such as `writeback-curator`, `evolution-planner`, and `scope-promoter`\n- skills such as `capability-evolution` and `project-operating-layer-design`\n\nThose built-in defaults become live when you manage a tool. Global tool management renders the bundled docs, agents, and skills into that tool’s live files. Project-local `.ai` roots do not sync the built-in operating-model layer unless you explicitly enable it.\n\nIf you want to disable default built-in sync for one canonical root:\n\n```toml\nversion = 1\n\n[builtin]\nsync_defaults = false\n```\n\nPut that in `config.toml` or `config.local.toml` under the active canonical root.\n\n## Use fclt from your agents\n\n`fclt` is CLI-first. The practical setup is:\n1. Install `fclt` globally so any agent runtime can execute it.\n2. Put allowed `fclt` workflows in your agent instructions and skills.\n3. Optionally scaffold MCP wrappers if you want an MCP entry that delegates to `fclt`.\n\n```bash\n# Scaffold reusable templates in the canonical store\nfclt templates init agents\nfclt templates init agent review-operator\nfclt templates init skill facult-manager\n\n# Enable that skill for managed tools\nfclt manage codex\nfclt manage cursor\nfclt manage claude\nfclt enable facult-manager --for codex,cursor,claude\nfclt sync\n```\n\nOptional MCP scaffold:\n\n```bash\nfclt templates init mcp facult-cli\nfclt enable mcp:facult-cli --for codex,cursor,claude\nfclt sync\n```\n\nNote: `templates init mcp ...` is a scaffold, not a running server by itself.\n\n## Mental Model\n\n`fclt` treats both `~/.ai` and `\u003crepo\u003e/.ai` as canonical stores. The global store is for personal reusable capability. The project store is for repo-owned capability that should travel with the codebase.\n\nTypical layout:\n\n```text\n~/.ai/\n  AGENTS.global.md\n  AGENTS.override.global.md\n  config.toml\n  config.local.toml\n  instructions/\n  snippets/\n  agents/\n  skills/\n  mcp/\n  templates/\n  tools/\n    codex/\n      config.toml\n      plugins/\n        marketplace.json\n      rules/\n\u003crepo\u003e/\n  .ai/\n    config.toml\n    instructions/\n    snippets/\n    agents/\n    skills/\n    tools/\n    .facult/\n      ai/\n        index.json\n        graph.json\n  .codex/\n  .agents/\n  plugins/\n  .claude/\n```\n\nImportant split:\n- `.ai/` is canonical source\n- `.ai/.facult/ai/` is generated AI state that belongs with the canonical root\n- machine-local Facult state such as managed-tool state, autosync runtime/config, install metadata, and launcher caches lives outside `.ai/`\n- tool homes such as `.codex/` and `.claude/` are rendered outputs\n- the generated capability graph lives at `.ai/.facult/ai/graph.json`\n\n### Asset types\n\nThe canonical store can contain several distinct asset classes:\n\n- `instructions/`: reusable doctrine and deeper conceptual guidance\n- `snippets/`: small composable blocks that can be inserted into rendered markdown\n- `agents/`: role-specific agent manifests\n- `skills/`: workflow-specific capability folders\n- `mcp/`: canonical MCP server definitions\n- `mcp/servers.local.json` or `mcp/mcp.local.json`: ignored machine-local MCP secret overlay\n- `tools/\u003ctool\u003e/config.toml`: canonical tool config\n- `tools/\u003ctool\u003e/config.local.toml`: machine-local tool config overlay\n- `tools/\u003ctool\u003e/rules/*.rules`: canonical tool rules\n- global docs such as `AGENTS.global.md` and `AGENTS.override.global.md`\n\nNot every asset syncs directly to a tool. Some exist primarily to support rendered outputs or to be discovered and reused by other canonical assets.\n\n### Canonical conventions\n\n- Use `instructions/` for reusable markdown documents\n- Use `snippets/` for composable partial blocks injected into markdown templates\n- Use `tools/codex/rules/*.rules` for actual Codex approval-policy rules\n- Use logical refs such as `@ai/instructions/WRITING.md` in tracked source\n- Use `@builtin/facult-operating-model/...` for packaged built-in defaults\n- Use `@project/...` when a tracked ref must resolve inside a repo-local `.ai`\n- Use config-backed refs in prompts where you want stable named references such as `${refs.writing_rule}`\n\n### Config and env layering\n\nCanonical render context is layered explicitly:\n1. built-ins injected by `fclt`\n2. active canonical root `config.toml`\n3. active canonical root `config.local.toml`\n4. explicit runtime overrides\n\nBuilt-ins currently include:\n- `AI_ROOT`\n- `HOME`\n- `PROJECT_ROOT`\n- `PROJECT_SLUG`\n- `TARGET_TOOL`\n- `TARGET_PATH`\n\nRecommended split:\n- `~/.ai/config.toml` or `\u003crepo\u003e/.ai/config.toml`: tracked, portable, non-secret refs/defaults\n- `~/.ai/config.local.toml` or `\u003crepo\u003e/.ai/config.local.toml`: ignored, machine-local paths and secrets\n- `~/.ai/mcp/servers.json` or `\u003crepo\u003e/.ai/mcp/servers.json`: tracked canonical MCP definitions\n- `~/.ai/mcp/servers.local.json` or `\u003crepo\u003e/.ai/mcp/servers.local.json`: ignored machine-local MCP env overlay for secrets and per-machine auth\n- `~/.ai/tools/\u003ctool\u003e/config.toml` or `\u003crepo\u003e/.ai/tools/\u003ctool\u003e/config.toml`: tracked tool defaults\n- `~/.ai/tools/\u003ctool\u003e/config.local.toml` or `\u003crepo\u003e/.ai/tools/\u003ctool\u003e/config.local.toml`: ignored, machine-local tool overrides merged after tracked tool config during sync\n- `[builtin].sync_defaults = false`: disable builtin default sync/materialization for this root\n- `[project_sync.\u003ctool\u003e]`: explicit project-managed allowlist for assets that may render into repo-local tool outputs\n- `fclt sync --builtin-conflicts overwrite`: allow packaged builtin defaults to overwrite locally modified generated targets\n- `fclt audit fix ...`: move inline MCP secrets from tracked canonical config into the local MCP overlay and re-sync managed tool configs\n\nFor project-local `.ai` roots, tool sync is default-deny. Nothing flows into repo-local managed tool outputs unless the repo explicitly opts in. Use `config.toml` or `config.local.toml` under the project root:\n\n```toml\nversion = 1\n\n[project_sync.codex]\nskills = [\"hack-cli\", \"hack-tickets\"]\nagents = [\"review-operator\"]\nmcp_servers = [\"github\"]\nglobal_docs = true\ntool_rules = true\ntool_config = true\n```\n\nThat policy applies to project-managed tool renders, including assets inherited from the merged global index. If you want a global skill inside a repo-local managed Codex output, name it explicitly here. `fclt doctor --repair` can materialize repo-local project assets into `config.local.toml` for already-managed project roots.\n\n### Snippets\n\nSnippets use HTML comment markers:\n\n```md\n\u003c!-- fclty:global/codex/baseline --\u003e\n\u003c!-- /fclty:global/codex/baseline --\u003e\n```\n\nResolution rules:\n- unscoped marker `codingstyle` prefers `snippets/projects/\u003cproject\u003e/codingstyle.md`, then falls back to `snippets/global/codingstyle.md`\n- explicit marker `global/codex/baseline` resolves directly to `snippets/global/codex/baseline.md`\n\nCommands:\n\n```bash\nfclt snippets list\nfclt snippets show global/codex/baseline\nfclt snippets sync [--dry-run] [file...]\n```\n\nSnippets are already used during global Codex `AGENTS.md` rendering.\n\n### Graph inspection\n\nThe generated graph in `.ai/.facult/ai/graph.json` is queryable directly:\n\n```bash\nfclt graph show instruction:WRITING\nfclt graph deps AGENTS.global.md\nfclt graph dependents @project/instructions/TESTING.md\n```\n\nThis is the explicit dependency layer for:\n- snippet markers like `\u003c!-- fclty:... --\u003e`\n- config-backed refs like `${refs.*}`\n- canonical refs like `@ai/...`\n- project refs like `@project/...`\n- rendered outputs such as managed agents, docs, MCP configs, tool configs, and tool rules\n\n### Writeback and evolution\n\n`fclt` also has a local writeback and evolution layer built on top of the graph:\n\n```bash\nfclt ai writeback add \\\n  --kind weak_verification \\\n  --summary \"Verification guidance did not distinguish shallow checks from meaningful proof.\" \\\n  --asset instruction:VERIFICATION \\\n  --tag verification \\\n  --tag false-positive\n\nfclt ai writeback list\nfclt ai writeback show WB-00001\nfclt ai writeback group --by asset\nfclt ai writeback summarize --by kind\nfclt ai evolve propose\nfclt ai evolve list\nfclt ai evolve show EV-00001\nfclt ai evolve draft EV-00001\nfclt ai evolve review EV-00001\nfclt ai evolve accept EV-00001\nfclt ai evolve reject EV-00001 --reason \"Needs a tighter draft\"\nfclt ai evolve supersede EV-00001 --by EV-00002\nfclt ai evolve apply EV-00001\nfclt ai evolve promote EV-00003 --to global --project\n```\n\nRuntime state stays generated and local inside the active canonical root:\n- global writeback state: `~/.ai/.facult/ai/global/...`\n- project writeback state: `\u003crepo\u003e/.ai/.facult/ai/project/...`\n\nThat split is intentional:\n- canonical source remains in `~/.ai` or `\u003crepo\u003e/.ai`\n- writeback queues, journals, proposal records, trust state, autosync state, and other generated runtime/config state stay inside `.ai/.facult/`\n- those records let agents inspect what changed, why it changed, and how it was reviewed\n\nUse writeback when:\n- a task exposed a weak or misleading verification loop\n- an instruction or agent was missing key context\n- a pattern proved reusable enough to become doctrine\n- a project-local pattern deserves promotion toward global capability\n\nDo not think of writeback as note-taking. Treat it as preserved signal that should improve the system.\n\nCurrent apply semantics are intentionally policy-bound:\n- targets are resolved through the generated graph when possible and fall back to canonical ref resolution for missing assets\n- apply is limited to markdown canonical assets\n- proposals must be drafted before they can be applied; higher-risk proposals still require explicit acceptance\n- supported proposal kinds currently include `create_instruction`, `update_instruction`, `create_agent`, `update_agent`, `update_asset`, `create_asset`, `extract_snippet`, `add_skill`, and `promote_asset`\n- low-risk project-scoped additive proposals such as `create_instruction` can be applied directly after drafting, while global and higher-risk proposals still require review/acceptance\n\nCurrent review/draft semantics:\n- `writeback group` and `writeback summarize` expose recurring patterns across `asset`, `kind`, and `domain` without mutating canonical assets\n- drafted proposals emit both a human-readable markdown draft and a patch artifact under generated state\n- rerunning `evolve draft \u003cid\u003e --append ...` revises the draft and records draft history\n- `evolve promote --to global` creates a new high-risk global proposal from a project-scoped proposal; that promoted proposal can then be drafted, reviewed, and applied into `~/.ai`\n\n### Scope and source selection\n\nMost inventory and sync commands support explicit canonical-root selection:\n\n- `--global` to force `~/.ai`\n- `--project` to force the nearest repo-local `.ai`\n- `--root /path/to/.ai` to point at a specific canonical root\n- `--scope merged|global|project` for discovery views\n- `--source builtin|global|project` to filter provenance in list/find/show/graph flows\n\n## Security and Trust\n\n`fclt` has two trust layers:\n- Item trust: `fclt trust \u003cname\u003e` / `fclt untrust \u003cname\u003e`\n- Source trust: `fclt sources ...` with levels `trusted`, `review`, `blocked`\n\nBulk trust annotations are also supported:\n\n```bash\nfclt trust --all\nfclt trust skills --all\nfclt untrust mcp --all\n```\n\n`fclt` also supports interactive and scripted audit flows:\n\n1. Interactive audit workflow:\n```bash\nfclt audit\n```\n2. Static audit rules (deterministic pattern checks):\n```bash\nfclt audit --non-interactive --severity high\nfclt audit --non-interactive mcp:github --severity medium --json\n```\n3. Agent-based audit (Claude/Codex review pass):\n```bash\nfclt audit --non-interactive --with claude --max-items 50\nfclt audit --non-interactive --with codex --max-items all --json\n```\n\n4. Suppress or remediate reviewed findings:\n```bash\nfclt audit safe mcp:github --rule static:mcp-env-inline-secret --note \"global managed render only\"\nfclt audit safe --all --source static --yes\nfclt audit fix mcp:github\nfclt audit fix --all --source combined --yes\n```\n\nRecommended security flow:\n1. `fclt verify-source \u003csource\u003e`\n2. `fclt sources trust \u003csource\u003e` only after review\n3. use `--strict-source-trust` for `install`/`update`\n4. keep tracked canonical MCP config secret-free; use `mcp/servers.local.json` for machine-local secrets\n5. run both static and agent audits on a schedule\n\n## Comprehensive Reference\n\n### Command categories\n\n- Inventory and discovery\n```bash\nfclt scan [--from \u003cpath\u003e] [--json] [--show-duplicates]\nfclt list [skills|mcp|agents|snippets|instructions] [--enabled-for \u003ctool\u003e] [--untrusted] [--flagged] [--pending]\nfclt show \u003cname\u003e\nfclt show instruction:\u003cname\u003e\nfclt show mcp:\u003cname\u003e [--show-secrets]\nfclt find \u003cquery\u003e [--json]\n```\n\n- Canonical store and migration\n```bash\nfclt consolidate [--auto keep-current|keep-incoming|keep-newest] [--from \u003cpath\u003e ...]\nfclt index [--force]\nfclt migrate [--from \u003cpath\u003e] [--dry-run] [--move] [--write-config]\n```\n\n- Managed mode and rollout\n```bash\nfclt manage \u003ctool\u003e [--dry-run] [--adopt-existing] [--existing-conflicts keep-canonical|keep-existing]\nfclt unmanage \u003ctool\u003e\nfclt managed\nfclt enable \u003cname\u003e [--for \u003ctool1,tool2,...\u003e]\nfclt enable mcp:\u003cname\u003e [--for \u003ctool1,tool2,...\u003e]\nfclt disable \u003cname\u003e [--for \u003ctool1,tool2,...\u003e]\nfclt trust --all\nfclt trust skills --all\nfclt untrust mcp --all\nfclt sync [tool] [--dry-run] [--builtin-conflicts overwrite]\nfclt autosync install [tool] [--git-remote \u003cname\u003e] [--git-branch \u003cname\u003e] [--git-interval-minutes \u003cn\u003e] [--git-disable]\nfclt autosync status [tool]\nfclt autosync restart [tool]\nfclt autosync uninstall [tool]\n```\n\n- Remote catalogs and policies\n```bash\nfclt search \u003cquery\u003e [--index \u003cname\u003e] [--limit \u003cn\u003e]\nfclt install \u003cindex:item\u003e [--as \u003cname\u003e] [--force] [--strict-source-trust]\nfclt update [--apply] [--strict-source-trust]\nfclt verify-source \u003cname\u003e [--json]\nfclt sources list\nfclt sources trust \u003csource\u003e [--note \u003ctext\u003e]\nfclt sources review \u003csource\u003e [--note \u003ctext\u003e]\nfclt sources block \u003csource\u003e [--note \u003ctext\u003e]\nfclt sources clear \u003csource\u003e\n```\n\n- Templates and snippets\n```bash\nfclt templates list\nfclt templates init project-ai\nfclt templates init skill \u003cname\u003e\nfclt templates init mcp \u003cname\u003e\nfclt templates init agent \u003cname\u003e\nfclt templates init snippet \u003cmarker\u003e\nfclt templates init agents\nfclt templates init automation \u003ctemplate-id\u003e --scope global|project|wide [--name \u003cname\u003e] [--project-root \u003cpath\u003e] [--cwds \u003cpath1,path2\u003e] [--rrule \u003cRRULE\u003e] [--status PAUSED|ACTIVE]\n\nfclt snippets list\nfclt snippets show \u003cmarker\u003e\nfclt snippets create \u003cmarker\u003e\nfclt snippets edit \u003cmarker\u003e\nfclt snippets sync [--dry-run] [file...]\n```\n\n### Codex automations\n\n`templates init automation` can scaffold three Codex automation forms:\n\n- `--scope project` (single repo): set `--project-root` (or infer from current working directory)\n- `--scope wide|global` (multiple repos): set `--cwds` explicitly; if omitted, created automation has no `cwds` by default.\n- If you run it interactively without `--scope`, `fclt` prompts for scope and, where possible, known workspaces (git worktrees, configured scan roots, and existing Codex automation paths).\n- Built-in automation templates are opinionated: they reference the global Codex operating model, point at relevant Codex skills, and tell Codex when to use focused subagents for bounded review work.\n\nRecommended topology:\n\n- Use `learning-review --scope project` for repo-local writeback and evolution. This keeps review state, verification, and follow-up scoped to the repo that actually produced the evidence.\n- Use `evolution-review` on a slower cadence, usually weekly, to triage open proposals and proposal-worthy clusters and suggest the next operator action (`draft`, `review`, `accept`, `reject`, `promote`, or `apply`).\n- Use a separate wide/global automation only for cross-repo or shared-surface review, such as global doctrine, shared skills, or repeated tool/agent patterns across repos.\n- If you do use a wide learning review, keep the `cwds` list intentionally small and related. The prompt is designed to partition by cwd first, not to blur unrelated repos together.\n- A practical default is daily `learning-review` plus weekly `evolution-review`. The first finds and records durable signal; the second keeps proposal review from stalling.\n\nFiles are written to:\n\n- `~/.codex/automations/\u003cname\u003e/automation.toml`\n- `~/.codex/automations/\u003cname\u003e/memory.md`\n\nWhen Codex is in managed mode, canonical automation sources live under:\n\n- `~/.ai/automations/\u003cname\u003e/...` for global automation state\n- `\u003crepo\u003e/.ai/automations/\u003cname\u003e/...` for project-scoped canonical state\n\nManaged 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.\n\nExample project automation:\n\n```bash\nfclt templates init automation tool-call-audit \\\n  --scope project \\\n  --project-root /path/to/repo \\\n  --name project-tool-audit \\\n  --status ACTIVE\n```\n\nExample global automation:\n\n```bash\nfclt templates init automation learning-review \\\n  --scope wide \\\n  --cwds /path/to/repo-a,/path/to/repo-b \\\n  --status PAUSED\n```\n\nExample weekly evolution automation:\n\n```bash\nfclt templates init automation evolution-review \\\n  --scope wide \\\n  --cwds /path/to/repo-a,/path/to/repo-b \\\n  --name weekly-evolution-review \\\n  --status PAUSED\n```\n\nInteractive prompt example:\n\n```bash\nfclt templates init automation learning-review\n# prompts for scope, then lets you select known workspaces or add custom paths.\n```\n\nFor full flags and exact usage:\n```bash\nfclt --help\nfclt \u003ccommand\u003e --help\n```\n\n### Root resolution\n\n`fclt` resolves the canonical root in this order:\n1. `FACULT_ROOT_DIR`\n2. nearest project `.ai` from the current working directory for CLI-facing commands\n3. `~/.ai/.facult/config.json` (`rootDir`)\n4. `~/.ai`\n5. `~/agents/.facult` (or a detected legacy store under `~/agents/`)\n\n### Runtime env vars\n\n- `FACULT_ROOT_DIR`: override canonical store location\n- `FACULT_VERSION`: version selector for `scripts/install.sh` (`latest` by default)\n- `FACULT_INSTALL_DIR`: install target dir for `scripts/install.sh` (`~/.ai/.facult/bin` by default)\n- `FACULT_INSTALL_PM`: force package manager detection for npm bootstrap launcher (`npm` or `bun`)\n\n### State and report files\n\nUnder canonical generated AI state (`~/.ai/.facult/` or `\u003crepo\u003e/.ai/.facult/`):\n- `sources.json` (latest inventory scan state)\n- `consolidated.json` (consolidation state)\n- `ai/index.json` (generated canonical AI inventory)\n- `audit/static-latest.json` (latest static audit report)\n- `audit/agent-latest.json` (latest agent audit report)\n- `trust/sources.json` (source trust policy state)\n\nUnder machine-local Facult state:\n- `install.json` (machine-local install metadata)\n- `global/managed.json` or `projects/\u003cslug-hash\u003e/managed.json` (managed tool state)\n- `.../autosync/services/*.json` (autosync service configs)\n- `.../autosync/state/*.json` (autosync runtime state)\n- `.../autosync/logs/*` (autosync service logs)\n- `runtime/\u003cversion\u003e/\u003cplatform-arch\u003e/...` under the machine-local cache root (npm launcher binary cache)\n\n### Config reference\n\n`~/.ai/.facult/config.json` supports:\n- `rootDir`\n- `scanFrom`\n- `scanFromIgnore`\n- `scanFromNoDefaultIgnore`\n- `scanFromMaxVisits`\n- `scanFromMaxResults`\n\n`scanFrom*` settings are used by `scan`/`audit` unless `--no-config-from` is passed.\n\nExample:\n```json\n{\n  \"rootDir\": \"~/.ai\",\n  \"scanFrom\": [\"~/dev\", \"~/work\"],\n  \"scanFromIgnore\": [\"vendor\", \".venv\"],\n  \"scanFromNoDefaultIgnore\": false,\n  \"scanFromMaxVisits\": 20000,\n  \"scanFromMaxResults\": 5000\n}\n```\n\n### Source aliases and custom indices\n\nDefault source aliases:\n- `facult` (builtin templates)\n- `smithery`\n- `glama`\n- `skills.sh`\n- `clawhub`\n\nCustom remote sources can be defined in `~/.ai/.facult/indices.json` (manifest URL, optional integrity, optional signature keys/signature verification settings).\n\n## Autosync\n\n`fclt autosync` is the background propagation layer for managed installs.\n\nCurrent v1 behavior:\n- macOS LaunchAgent-backed\n- immediate local managed-tool sync on the configured canonical root\n- periodic git autosync for the canonical repo\n- automatic autosync commits with source-tagged commit messages such as:\n  - `chore(facult-autosync): sync canonical ai changes from \u003chost\u003e [service:all]`\n\nRecommended usage:\n\n```bash\nfclt autosync install\nfclt autosync status\n```\n\nTool-scoped or project-local usage:\n\n```bash\ncd /path/to/repo\nfclt autosync install codex\nfclt autosync status codex\n```\n\nOne-shot runner for verification/debugging:\n\n```bash\nfclt autosync run --service all --once\n```\n\nRemote git policy:\n- do not sync on every file event\n- mark the canonical repo dirty on local changes\n- on the configured timer, fetch, auto-commit local canonical changes if needed, pull `--rebase`, then push\n- if rebase conflicts occur, remote autosync is blocked and reported, but local managed-tool sync keeps running\n\n## Commit Hygiene\n\nSome MCP config files can contain secrets. Keep local generated artifacts and secret-bearing config files ignored and out of commits.\n\nRecommended practice:\n- tracked canonical MCP definitions in `mcp/servers.json` should not inline secrets\n- machine-local secrets belong in `mcp/servers.local.json` or `mcp/mcp.local.json`\n- global rendered configs under `~/.codex`, `~/.claude`, or similar can contain merged secret values as machine-local runtime output\n- repo-local rendered configs should be gitignored; `fclt audit` now flags inline secrets more aggressively when the destination is git-tracked or repo-local and not ignored\n\n## Contributing\n\nContributor and release workflow details live in [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## FAQ\n\n### Does fclt run its own MCP server today?\n\nNot as a first-party `fclt mcp serve` runtime.\n\n`fclt` currently focuses on inventory, trust/audit, install/update, and managed sync of canonical AI capability and tool-native outputs.\n\n### Does fclt now manage global AI config, not just skills and MCP?\n\nYes. The core model now includes:\n- canonical personal AI source in `~/.ai`\n- rendered managed outputs in tool homes such as `~/.codex`, `~/.agents`, and `~/plugins`\n- global instruction docs such as `AGENTS.global.md`, rendered by default into `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, and `~/.cursor/AGENTS.md`\n- Codex-authored skills in `~/.agents/skills`\n- Codex local plugin marketplaces in `~/.agents/plugins/marketplace.json`\n- Codex local plugin bundles in `~/plugins/\u003cplugin-name\u003e`\n- tool-native configs such as `~/.codex/config.toml`\n- tool-native rule files such as `~/.codex/rules/*.rules`\n\n### Do I still need to run `fclt sync` manually?\n\nIf autosync is not installed, yes.\n\nIf autosync is installed, local changes under `~/.ai` propagate automatically to managed tools. Manual `fclt sync` is still useful for explicit repair, dry-runs, and non-daemon workflows.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhack-dance%2Ffclt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhack-dance%2Ffclt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhack-dance%2Ffclt/lists"}