facult 1.2.1 → 2.0.1

package/README.md

@@ -1,4 +1,4 @@
-# facult
+# fclt
 
 <div align="center">
   <a aria-label="NPM version" href="https://www.npmjs.com/package/facult">
@@ -15,34 +15,41 @@
   </a>
 </div>
 
-`facult` is a CLI for managing canonical AI capability across tools, users, and projects.
+`fclt` is a CLI for building and evolving AI faculties across tools, users, and projects.
+
+Most AI tooling manages files. `fclt` manages faculties: the instructions, snippets, templates, skills, agents, rules, and learning loops that should compound, improve, and survive the next session.
 
 It helps you:
-- discover what is installed on your machine
-- consolidate everything into one canonical store
-- review trust/security before installing remote content
-- sync managed outputs into Codex, Cursor, and Claude
-- manage a git-backed AI store under `~/.ai` and repo-local `.ai/`
-- model relationships between instructions, snippets, agents, skills, and rendered tool outputs
+- turn repeated friction into reusable capability
 - preserve learning through writeback and evolve canonical assets over time
+- consolidate AI behavior into one canonical store
+- compose prompts, agents, skills, and tool outputs from reusable snippets and templates
+- discover what exists, what depends on what, and what should change next
+- sync managed outputs into Codex, Cursor, and Claude
+- review trust/security before installing remote content
+- keep that operating layer in a git-backed store under `~/.ai` and repo-local `.ai/`
 
-## What facult Is
+## What fclt Is
 
-If your agent setup feels scattered (`~/.codex`, `~/.agents`, tool-specific MCP JSON/TOML), `facult` gives you one place to manage it safely.
+If your agent setup feels scattered, `fclt` gives it memory, structure, and a way to improve.
+
+A faculty is a reusable piece of AI behavior: an instruction, snippet, template, skill, agent, rule, or learned improvement that you want to keep around and make better.
+
+That matters because a lot of useful AI behavior is compositional. You want small reusable blocks, a clean way to assemble them into bigger prompts and operating layers, and a safe way to render the final tool-native outputs without losing the source structure.
 
 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 and project AI instructions, snippets, agents, skills, tool configs, and rules
-- a local capability graph for discovering what exists and what depends on what
+- a canonical home for your AI faculties
+- a composition system for snippets, templates, and rendered AI behavior
+- a sync layer for projecting them into real tools
+- a discovery graph for seeing what exists and what depends on what
 - a writeback/evolution loop for turning repeated friction into durable improvements
+- an inventory and trust boundary for the assets you let into the system
 
-## What facult Does
+## What fclt Does
 
-`facult` is not just a skill manager.
+`fclt` is not a skills folder with a nicer CLI.
 
-It provides five connected layers:
+It works as five connected layers:
 
 1. Canonical source
    - global capability in `~/.ai`
@@ -65,7 +72,7 @@ It provides five connected layers:
 
 ## Default Operating Model
 
-`facult` ships with a built-in Facult operating-model pack. That pack includes default:
+`fclt` ships with a built-in operating model for learning, writeback, and capability evolution. That pack includes default:
 
 - instructions for evolution, integration, and project capability
 - specialist agents such as `writeback-curator`, `evolution-planner`, and `scope-promoter`
@@ -76,14 +83,14 @@ When managed sync is enabled, these built-in assets are available by default eve
 That means:
 - builtin skills sync into managed tool skill directories by default
 - builtin agents sync into tool agent directories when the tool supports agents
-- if you do not author your own `AGENTS.global.md`, `facult` renders a builtin global baseline doc into tool-native global docs
+- if you do not author your own `AGENTS.global.md`, `fclt` renders a builtin global baseline doc into tool-native global docs
 
 This is intentionally virtual at the canonical level:
 - builtin defaults remain part of the packaged tool
 - your personal `~/.ai` stays clean unless you explicitly vendor or override something
 - the live tool output on disk still contains the rendered defaults, so users and agents can read them directly
 
-In practice, this means you do not need to drive writeback and evolution through the CLI alone. The default skills, agents, and global docs are meant to make that operating model available automatically.
+In practice, this means the system is meant to learn by default. The CLI is there when you want to operate it directly, but the default skills, agents, and global docs are supposed to make writeback and evolution available without ceremony.
 
 If you want to disable the builtin default layer for a specific global or project canonical root:
 
@@ -100,11 +107,11 @@ Put that in `config.toml` or `config.local.toml` under the active canonical root
 
 ### Canonical vs rendered
 
-`facult` separates source-of-truth from tool-native output.
+`fclt` separates source-of-truth from tool-native output.
 
 - canonical source lives in `~/.ai` or `<repo>/.ai`
 - rendered outputs live in tool homes like `~/.codex`, `<repo>/.codex`, `~/.claude`, or `~/.cursor`
-- generated state lives in `~/.facult` or `<repo>/.facult`
+- generated Facult-owned state lives in `~/.ai/.facult` or `<repo>/.ai/.facult`
 
 This keeps authored capability portable and reviewable while still producing the exact files each tool expects.
 
@@ -126,7 +133,7 @@ Project capability is allowed to extend or shadow global capability in merged vi
 
 ### The capability graph
 
-`facult` builds a generated graph of explicit relationships between canonical assets and rendered outputs.
+`fclt` builds a generated graph of explicit relationships between canonical assets and rendered outputs.
 
 That graph tracks things like:
 - snippet markers
@@ -142,22 +149,24 @@ This makes it possible to answer:
 
 ### Writeback and evolution
 
-`facult` treats repeated failures, weak loops, missing context, and reusable patterns as signal worth preserving.
+`fclt` treats repeated failures, weak loops, missing context, and reusable patterns as signal worth preserving.
 
 Writeback is the act of recording that signal in a structured way.
 Evolution is the act of grouping that signal into reviewable proposals and applying it back into canonical assets.
 
-This matters because otherwise the same problems repeat in chat without ever improving the actual operating layer. With `facult`, you can:
+This matters because otherwise the same problems repeat in chat without ever improving the actual operating layer. With `fclt`, you can:
 - record a weak verification pattern
 - group repeated writebacks around an instruction or agent
 - draft a proposal to tighten that canonical asset
 - review and apply the change in a controlled way
 
-The result is that your AI system can get better over time without hiding mutations in tool-specific state or losing the reasoning behind a change.
+The point is not just better storage. The point is that your AI setup can change shape as it learns.
+
+That is the core idea behind `fclt`: not just syncing skills, but growing faculties.
 
 ## Quick Start
 
-### 1. Install facult
+### 1. Install fclt
 
 Recommended global install:
 
@@ -165,45 +174,46 @@ Recommended global install:
 npm install -g facult
 # or
 bun add -g facult
-facult --help
+fclt --help
 ```
 
+The npm package name stays `facult` for registry compatibility. The installed command is still `fclt`.
+
 One-off usage without global install:
 
 ```bash
-npx facult --help
-bunx facult --help
+npx --yes -p facult fclt --help
 ```
 
 Direct binary install from GitHub Releases (macOS/Linux):
 
 ```bash
-curl -fsSL https://github.com/hack-dance/facult/releases/latest/download/facult-install.sh | bash
+curl -fsSL https://github.com/hack-dance/facult/releases/latest/download/fclt-install.sh | bash
 ```
 
 Windows and manual installs can download the correct binary from each release page:
-`facult-<version>-<platform>-<arch>`.
+`fclt-<version>-<platform>-<arch>`.
 
 Update later with:
 
 ```bash
-facult self-update
+fclt self-update
 # or
-facult update --self
+fclt update --self
 ```
 
 Pin to a specific version:
 
 ```bash
-facult self-update --version 0.0.1
+fclt self-update --version 0.0.1
 ```
 
 ### 2. Start with a read-only inventory (recommended first)
 
 ```bash
-facult scan --show-duplicates
+fclt scan --show-duplicates
 # optional machine-readable output
-facult scan --json
+fclt scan --json
 ```
 
 `scan` is read-only. It inspects local configs and reports what `facult` found without changing files.
@@ -211,68 +221,68 @@ facult scan --json
 ### 3. Import existing skills/configs
 
 ```bash
-facult consolidate --auto keep-current --from ~/.codex/skills --from ~/.agents/skills
-facult index
+fclt consolidate --auto keep-current --from ~/.codex/skills --from ~/.agents/skills
+fclt index
 ```
 
 Why `keep-current`: it is deterministic and non-interactive for duplicate sources.
 
-Canonical source root: `~/.ai` for global work, or `<repo>/.ai` for project-local work. Generated state lives next to the active canonical root:
-- global: `~/.facult`
-- project: `<repo>/.facult`
+Canonical source root: `~/.ai` for global work, or `<repo>/.ai` for project-local work. Facult-owned generated/config/runtime state lives inside the active canonical root:
+- global: `~/.ai/.facult`
+- project: `<repo>/.ai/.facult`
 
 ### 3b. Bootstrap a repo-local `.ai`
 
 ```bash
 cd /path/to/repo
-bunx facult templates init project-ai
-bunx facult index
+bunx fclt templates init project-ai
+bunx fclt index
 ```
 
-This seeds `<repo>/.ai` from the built-in Facult operating-model pack and writes a merged project index/graph under `<repo>/.facult/ai/`.
+This seeds `<repo>/.ai` from the built-in Facult operating-model pack and writes a merged project index/graph under `<repo>/.ai/.facult/ai/`.
 
 ### 4. Inspect what you have
 
 ```bash
-facult list skills
-facult list instructions
-facult list mcp
-facult show requesting-code-review
-facult show instruction:WRITING
-facult show mcp:github
-facult find verification
-facult graph show instruction:WRITING
-facult graph deps AGENTS.global.md
-facult graph dependents @ai/instructions/WRITING.md
-facult ai writeback add --kind weak_verification --summary "Checks were too shallow" --asset instruction:VERIFICATION
-facult ai evolve propose
-facult ai evolve draft EV-00001
-facult ai evolve accept EV-00001
-facult ai evolve apply EV-00001
+fclt list skills
+fclt list instructions
+fclt list mcp
+fclt show requesting-code-review
+fclt show instruction:WRITING
+fclt show mcp:github
+fclt find verification
+fclt graph show instruction:WRITING
+fclt graph deps AGENTS.global.md
+fclt graph dependents @ai/instructions/WRITING.md
+fclt ai writeback add --kind weak_verification --summary "Checks were too shallow" --asset instruction:VERIFICATION
+fclt ai evolve propose
+fclt ai evolve draft EV-00001
+fclt ai evolve accept EV-00001
+fclt ai evolve apply EV-00001
 ```
 
 Context controls:
 
 ```bash
-facult list instructions --global
-facult list instructions --project
-facult find verification --scope merged --source project
-facult sync codex --project
-facult autosync status --global
-facult list agents --root /path/to/repo/.ai
+fclt list instructions --global
+fclt list instructions --project
+fclt find verification --scope merged --source project
+fclt sync codex --project
+fclt autosync status --global
+fclt list agents --root /path/to/repo/.ai
 ```
 
 ### 5. Enable managed mode for your tools
 
 ```bash
-facult manage codex --dry-run
-facult manage codex --adopt-existing
-facult sync codex --builtin-conflicts overwrite
-facult manage cursor
-facult manage claude
+fclt manage codex --dry-run
+fclt manage codex --adopt-existing
+fclt sync codex --builtin-conflicts overwrite
+fclt manage cursor
+fclt manage claude
 
-facult enable requesting-code-review receiving-code-review brainstorming systematic-debugging --for codex,cursor,claude
-facult sync
+fclt enable requesting-code-review receiving-code-review brainstorming systematic-debugging --for codex,cursor,claude
+fclt sync
 ```
 
 At this point, your selected skills are actively synced to all managed tools.
@@ -283,8 +293,8 @@ For builtin-backed rendered defaults, `facult` now tracks the last managed rende
 ### 6. Turn on background autosync
 
 ```bash
-facult autosync install --git-remote origin --git-branch main --git-interval-minutes 60
-facult autosync status
+fclt autosync install --git-remote origin --git-branch main --git-interval-minutes 60
+fclt autosync status
 ```
 
 This installs a macOS LaunchAgent that:
@@ -297,14 +307,14 @@ If the repo hits a rebase conflict, remote autosync stops and reports the blocke
 ### 7. Turn on source trust and strict install flow
 
 ```bash
-facult sources list
-facult verify-source skills.sh --json
-facult sources trust skills.sh --note "reviewed"
+fclt sources list
+fclt verify-source skills.sh --json
+fclt sources trust skills.sh --note "reviewed"
 
-facult install skills.sh:code-review --as code-review-skills-sh --strict-source-trust
+fclt install skills.sh:code-review --as code-review-skills-sh --strict-source-trust
 ```
 
-## Use facult from your agents
+## Use fclt from your agents
 
 `facult` is CLI-first. The practical setup is:
 1. Install `facult` globally so any agent runtime can execute it.
@@ -313,24 +323,24 @@ facult install skills.sh:code-review --as code-review-skills-sh --strict-source-
 
 ```bash
 # Scaffold reusable templates in the canonical store
-facult templates init agents
-facult templates init claude
-facult templates init skill facult-manager
+fclt templates init agents
+fclt templates init claude
+fclt templates init skill facult-manager
 
 # Enable that skill for managed tools
-facult manage codex
-facult manage cursor
-facult manage claude
-facult enable facult-manager --for codex,cursor,claude
-facult sync
+fclt manage codex
+fclt manage cursor
+fclt manage claude
+fclt enable facult-manager --for codex,cursor,claude
+fclt sync
 ```
 
 Optional MCP scaffold:
 
 ```bash
-facult templates init mcp facult-cli
-facult enable mcp:facult-cli --for codex,cursor,claude
-facult sync
+fclt templates init mcp facult-cli
+fclt enable mcp:facult-cli --for codex,cursor,claude
+fclt sync
 ```
 
 Note: `templates init mcp ...` is a scaffold, not a running server by itself.
@@ -365,19 +375,19 @@ Typical layout:
     agents/
     skills/
     tools/
-  .facult/
-    ai/
-      index.json
-      graph.json
+    .facult/
+      ai/
+        index.json
+        graph.json
   .codex/
   .claude/
 ```
 
 Important split:
 - `.ai/` is canonical source
-- `.facult/` is generated state, trust state, managed tool state, autosync state, and caches
+- `.ai/.facult/` is Facult-owned generated state, trust state, managed tool state, autosync state, and caches
 - tool homes such as `.codex/` and `.claude/` are rendered outputs
-- the generated capability graph lives at `.facult/ai/graph.json`
+- the generated capability graph lives at `.ai/.facult/ai/graph.json`
 
 ### Asset types
 
@@ -408,11 +418,9 @@ Not every asset syncs directly to a tool. Some exist primarily to support render
 
 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
+2. active canonical root `config.toml`
+3. active canonical root `config.local.toml`
+4. explicit runtime overrides
 
 Built-ins currently include:
 - `AI_ROOT`
@@ -423,10 +431,10 @@ Built-ins currently include:
 - `TARGET_PATH`
 
 Recommended split:
-- `config.toml`: tracked, portable, non-secret refs/defaults
-- `config.local.toml`: ignored, machine-local paths and secrets
+- `~/.ai/config.toml` or `<repo>/.ai/config.toml`: tracked, portable, non-secret refs/defaults
+- `~/.ai/config.local.toml` or `<repo>/.ai/config.local.toml`: ignored, machine-local paths and secrets
 - `[builtin].sync_defaults = false`: disable builtin default sync/materialization for this root
-- `facult sync --builtin-conflicts overwrite`: allow packaged builtin defaults to overwrite locally modified generated targets
+- `fclt sync --builtin-conflicts overwrite`: allow packaged builtin defaults to overwrite locally modified generated targets
 
 ### Snippets
 
@@ -444,21 +452,21 @@ Resolution rules:
 Commands:
 
 ```bash
-facult snippets list
-facult snippets show global/codex/baseline
-facult snippets sync [--dry-run] [file...]
+fclt snippets list
+fclt snippets show global/codex/baseline
+fclt snippets sync [--dry-run] [file...]
 ```
 
 Snippets are already used during global Codex `AGENTS.md` rendering.
 
 ### Graph inspection
 
-The generated graph in `.facult/ai/graph.json` is queryable directly:
+The generated graph in `.ai/.facult/ai/graph.json` is queryable directly:
 
 ```bash
-facult graph show instruction:WRITING
-facult graph deps AGENTS.global.md
-facult graph dependents @project/instructions/TESTING.md
+fclt graph show instruction:WRITING
+fclt graph deps AGENTS.global.md
+fclt graph dependents @project/instructions/TESTING.md
 ```
 
 This is the explicit dependency layer for:
@@ -473,36 +481,36 @@ This is the explicit dependency layer for:
 `facult` also has a local writeback/evolution substrate built on top of the graph:
 
 ```bash
-facult ai writeback add \
+fclt ai writeback add \
   --kind weak_verification \
   --summary "Verification guidance did not distinguish shallow checks from meaningful proof." \
   --asset instruction:VERIFICATION \
   --tag verification \
   --tag false-positive
 
-facult ai writeback list
-facult ai writeback show WB-00001
-facult ai writeback group --by asset
-facult ai writeback summarize --by kind
-facult ai evolve propose
-facult ai evolve list
-facult ai evolve show EV-00001
-facult ai evolve draft EV-00001
-facult ai evolve review EV-00001
-facult ai evolve accept EV-00001
-facult ai evolve reject EV-00001 --reason "Needs a tighter draft"
-facult ai evolve supersede EV-00001 --by EV-00002
-facult ai evolve apply EV-00001
-facult ai evolve promote EV-00003 --to global --project
-```
-
-Runtime state stays generated and local:
-- global writeback state: `~/.facult/ai/global/...`
-- project writeback state: `~/.facult/ai/projects/<slug>/...`
+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 "Needs a tighter draft"
+fclt ai evolve supersede EV-00001 --by EV-00002
+fclt ai evolve apply EV-00001
+fclt ai evolve promote EV-00003 --to global --project
+```
+
+Runtime state stays generated and local inside the active canonical root:
+- global writeback state: `~/.ai/.facult/ai/global/...`
+- project writeback state: `<repo>/.ai/.facult/ai/project/...`
 
 That split is intentional:
 - canonical source remains in `~/.ai` or `<repo>/.ai`
-- writeback queues, journals, and proposal records stay outside the canonical git-backed tree by default
+- writeback queues, journals, proposal records, trust state, autosync state, and other Facult-owned runtime/config state stay inside `.ai/.facult/` rather than inside the tool homes
 
 Use writeback when:
 - a task exposed a weak or misleading verification loop
@@ -512,7 +520,7 @@ Use writeback when:
 
 Do not think of writeback as “taking notes.” Think of it as preserving signal that should change the system, not just the current conversation.
 
-For many users, the normal entrypoint is not the CLI directly. The builtin operating-model layer is designed so synced agents, skills, and global docs can push the system toward writeback and evolution by default, while the `facult ai ...` commands remain the explicit operator surface when you want direct control.
+For many users, the normal entrypoint is not the CLI directly. The builtin operating-model layer is designed so synced agents, skills, and global docs can push the system toward writeback and evolution by default, while the `fclt ai ...` commands remain the explicit operator surface when you want direct control.
 
 Current apply semantics are intentionally policy-bound:
 - targets are resolved through the generated graph when possible and fall back to canonical ref resolution for missing assets
@@ -540,29 +548,29 @@ Most inventory and sync commands support explicit canonical-root selection:
 ## Security and Trust
 
 `facult` has two trust layers:
-- Item trust: `facult trust <name>` / `facult untrust <name>`
-- Source trust: `facult sources ...` with levels `trusted`, `review`, `blocked`
+- Item trust: `fclt trust <name>` / `fclt untrust <name>`
+- Source trust: `fclt sources ...` with levels `trusted`, `review`, `blocked`
 
 `facult` also supports two audit modes:
 
 1. Interactive audit workflow:
 ```bash
-facult audit
+fclt audit
 ```
 2. Static audit rules (deterministic pattern checks):
 ```bash
-facult audit --non-interactive --severity high
-facult audit --non-interactive mcp:github --severity medium --json
+fclt audit --non-interactive --severity high
+fclt audit --non-interactive mcp:github --severity medium --json
 ```
 3. Agent-based audit (Claude/Codex review pass):
 ```bash
-facult audit --non-interactive --with claude --max-items 50
-facult audit --non-interactive --with codex --max-items all --json
+fclt audit --non-interactive --with claude --max-items 50
+fclt audit --non-interactive --with codex --max-items all --json
 ```
 
 Recommended security flow:
-1. `facult verify-source <source>`
-2. `facult sources trust <source>` only after review
+1. `fclt verify-source <source>`
+2. `fclt sources trust <source>` only after review
 3. use `--strict-source-trust` for `install`/`update`
 4. run both static and agent audits on a schedule
 
@@ -581,70 +589,70 @@ Recommended security flow:
 
 - Inventory and discovery
 ```bash
-facult scan [--from <path>] [--json] [--show-duplicates]
-facult list [skills|mcp|agents|snippets|instructions] [--enabled-for <tool>] [--untrusted] [--flagged] [--pending]
-facult show <name>
-facult show instruction:<name>
-facult show mcp:<name> [--show-secrets]
-facult find <query> [--json]
+fclt scan [--from <path>] [--json] [--show-duplicates]
+fclt list [skills|mcp|agents|snippets|instructions] [--enabled-for <tool>] [--untrusted] [--flagged] [--pending]
+fclt show <name>
+fclt show instruction:<name>
+fclt show mcp:<name> [--show-secrets]
+fclt find <query> [--json]
 ```
 
 - Canonical store and migration
 ```bash
-facult consolidate [--auto keep-current|keep-incoming|keep-newest] [--from <path> ...]
-facult index [--force]
-facult migrate [--from <path>] [--dry-run] [--move] [--write-config]
+fclt consolidate [--auto keep-current|keep-incoming|keep-newest] [--from <path> ...]
+fclt index [--force]
+fclt migrate [--from <path>] [--dry-run] [--move] [--write-config]
 ```
 
 - Managed mode and rollout
 ```bash
-facult manage <tool> [--dry-run] [--adopt-existing] [--existing-conflicts keep-canonical|keep-existing]
-facult unmanage <tool>
-facult managed
-facult enable <name> [--for <tool1,tool2,...>]
-facult enable mcp:<name> [--for <tool1,tool2,...>]
-facult disable <name> [--for <tool1,tool2,...>]
-facult sync [tool] [--dry-run] [--builtin-conflicts overwrite]
-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]
+fclt manage <tool> [--dry-run] [--adopt-existing] [--existing-conflicts keep-canonical|keep-existing]
+fclt unmanage <tool>
+fclt managed
+fclt enable <name> [--for <tool1,tool2,...>]
+fclt enable mcp:<name> [--for <tool1,tool2,...>]
+fclt disable <name> [--for <tool1,tool2,...>]
+fclt sync [tool] [--dry-run] [--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]
+fclt autosync uninstall [tool]
 ```
 
 - Remote catalogs and policies
 ```bash
-facult search <query> [--index <name>] [--limit <n>]
-facult install <index:item> [--as <name>] [--force] [--strict-source-trust]
-facult update [--apply] [--strict-source-trust]
-facult verify-source <name> [--json]
-facult sources list
-facult sources trust <source> [--note <text>]
-facult sources review <source> [--note <text>]
-facult sources block <source> [--note <text>]
-facult sources clear <source>
+fclt search <query> [--index <name>] [--limit <n>]
+fclt install <index:item> [--as <name>] [--force] [--strict-source-trust]
+fclt update [--apply] [--strict-source-trust]
+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>
 ```
 
 - Templates and snippets
 ```bash
-facult templates list
-facult templates init project-ai
-facult templates init skill <name>
-facult templates init mcp <name>
-facult templates init snippet <marker>
-facult templates init agents
-facult templates init claude
+fclt templates list
+fclt templates init project-ai
+fclt templates init skill <name>
+fclt templates init mcp <name>
+fclt templates init snippet <marker>
+fclt templates init agents
+fclt templates init claude
 
-facult snippets list
-facult snippets show <marker>
-facult snippets create <marker>
-facult snippets edit <marker>
-facult snippets sync [--dry-run] [file...]
+fclt snippets list
+fclt snippets show <marker>
+fclt snippets create <marker>
+fclt snippets edit <marker>
+fclt snippets sync [--dry-run] [file...]
 ```
 
 For full flags and exact usage:
 ```bash
-facult --help
-facult <command> --help
+fclt --help
+fclt <command> --help
 ```
 
 ### Root resolution
@@ -652,7 +660,7 @@ facult <command> --help
 `facult` resolves the canonical root in this order:
 1. `FACULT_ROOT_DIR`
 2. nearest project `.ai` from the current working directory for CLI-facing commands
-3. `~/.facult/config.json` (`rootDir`)
+3. `~/.ai/.facult/config.json` (`rootDir`)
 4. `~/.ai`
 5. `~/agents/.facult` (or a detected legacy store under `~/agents/`)
 
@@ -660,12 +668,12 @@ facult <command> --help
 
 - `FACULT_ROOT_DIR`: override canonical store location
 - `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_DIR`: install target dir for `scripts/install.sh` (`~/.ai/.facult/bin` by default)
 - `FACULT_INSTALL_PM`: force package manager detection for npm bootstrap launcher (`npm` or `bun`)
 
 ### State and report files
 
-Under `~/.facult/`:
+Under `~/.ai/.facult/`:
 - `sources.json` (latest inventory scan state)
 - `consolidated.json` (consolidation state)
 - `managed.json` (managed tool state)
@@ -679,7 +687,7 @@ Under `~/.facult/`:
 
 ### Config reference
 
-`~/.facult/config.json` supports:
+`~/.ai/.facult/config.json` supports:
 - `rootDir`
 - `scanFrom`
 - `scanFromIgnore`
@@ -710,7 +718,7 @@ Default source aliases:
 - `skills.sh`
 - `clawhub`
 
-Custom remote sources can be defined in `~/.facult/indices.json` (manifest URL, optional integrity, optional signature keys/signature verification settings).
+Custom remote sources can be defined in `~/.ai/.facult/indices.json` (manifest URL, optional integrity, optional signature keys/signature verification settings).
 
 ## Local Install Modes
 
@@ -722,11 +730,11 @@ bun run install:bin
 bun run install:status
 ```
 
-Default install path is `~/.facult/bin/facult`. You can pass a custom target dir via `--dir=/path`.
+Default install path is `~/.ai/.facult/bin/fclt`. You can pass a custom target dir via `--dir=/path`.
 
 ## Autosync
 
-`facult autosync` is the background propagation layer for managed installs.
+`fclt autosync` is the background propagation layer for managed installs.
 
 Current v1 behavior:
 - macOS LaunchAgent-backed
@@ -738,28 +746,28 @@ Current v1 behavior:
 Recommended usage:
 
 ```bash
-facult autosync install
-facult autosync status
+fclt autosync install
+fclt autosync status
 ```
 
 Project-local usage:
 
 ```bash
 cd /path/to/repo
-facult autosync install codex
-facult autosync status codex
+fclt autosync install codex
+fclt autosync status codex
 ```
 
 Tool-scoped service:
 
 ```bash
-facult autosync install codex
+fclt autosync install codex
 ```
 
 One-shot runner for verification/debugging:
 
 ```bash
-facult autosync run --service all --once
+fclt autosync run --service all --once
 ```
 
 Remote git policy:
@@ -780,7 +788,7 @@ Release behavior:
 3. The same release workflow then builds platform binaries and uploads them to that GitHub release.
 4. npm publish runs only after binary asset upload succeeds (`publish-npm` depends on `publish-assets`).
 5. Published release assets include platform binaries, `facult-install.sh`, and `SHA256SUMS`.
-6. The npm package launcher resolves your platform, downloads the matching release binary, caches it under `~/.facult/runtime/<version>/<platform-arch>/`, and runs it.
+6. The npm package launcher resolves your platform, downloads the matching release binary, caches it under `~/.ai/.facult/runtime/<version>/<platform-arch>/`, and runs it.
 
 Current prebuilt binary targets:
 - `darwin-x64`
@@ -791,7 +799,7 @@ Current prebuilt binary targets:
 Self-update behavior:
 1. npm/bun global install: updates via package manager (`npm install -g facult@...` or `bun add -g facult@...`).
 2. Direct binary install (release script/local binary path): downloads and replaces the binary in place.
-3. Use `facult self-update` (or `facult update --self`).
+3. Use `fclt self-update` (or `fclt update --self`).
 
 Required secrets for publish:
 - `NPM_TOKEN`
@@ -829,13 +837,13 @@ bun run release:dry-run
 
 ## FAQ
 
-### Does facult run its own MCP server today?
+### Does fclt run its own MCP server today?
 
-Not as a first-party `facult mcp serve` runtime.
+Not as a first-party `fclt 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?
+### Does fclt now manage global AI config, not just skills and MCP?
 
 Yes. The core model now includes:
 - canonical personal AI source in `~/.ai`
@@ -844,8 +852,8 @@ Yes. The core model now includes:
 - 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?
+### Do I still need to run `fclt 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.
+If 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.