facult 2.12.0 → 2.13.0

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/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

package/docs/roadmap.md

@@ -1,6 +1,6 @@
 # Roadmap
 
-This replaces the older operating-model target-state notes. That file mixed current documentation, past investigation output, and future design ideas. The current docs now describe shipped behavior; this file tracks remaining product direction.
+This roadmap tracks remaining product direction for `fclt`.
 
 ## Already Shipped
 
@@ -11,6 +11,7 @@ This replaces the older operating-model target-state notes. That file mixed curr
 - Project-scoped writeback/evolution artifacts mirrored under global `~/.ai`.
 - Built-in operating-model pack.
 - Independent built-in operating-model pack install with `templates init operating-model`.
+- Read-only setup discovery with `doctor --json` and `paths --json`.
 - Cleaner built-in canonical refs.
 - JSON-first `inventory`.
 - `sync --adopt-live` for explicit promotion of live tool edits.
@@ -18,32 +19,42 @@ This replaces the older operating-model target-state notes. That file mixed curr
 
 ## Current Priorities
 
-1. Make status more explanatory.
+1. Add agent-first setup APIs.
+   - Add `setup plan --json` and safe apply primitives for confirmation-gated setup.
+   - Add command/risk metadata so agents can distinguish read-only, dry-run, generated-state writes, mutating actions, and high-risk global changes.
+
+2. Make status more explanatory.
    - Show policy summaries.
    - Surface top recommended next action.
    - Connect sync ledger history to rendered targets.
 
-2. Add a structured sync plan.
+3. Add a structured sync plan.
    - Group writes, updates, removals, skips, conflicts, and repairs.
    - Expose the same plan as JSON.
    - Explain source refs and policy reasons.
 
-3. Improve project onboarding.
+4. Improve project onboarding.
    - Add a primary `fclt init project` flow.
    - Explain default-deny project sync during setup.
    - Offer safe adoption, detach, and restore choices.
 
-4. Make policy inspectable.
+5. Make policy inspectable.
    - Add `policy show`.
    - Add `policy explain`.
    - Hide TOML details behind user-facing commands where possible.
 
-5. Make templates, plugins, automations, and rendered targets first-class inventory objects.
+6. Make templates, plugins, automations, and rendered targets first-class inventory objects.
    - List and show them consistently.
    - Add graph visibility.
    - Include them in status and sync plans.
 
-6. Tighten selector consistency.
+7. Add a first-party Codex plugin and MCP surface.
+   - Expose safe read/write operations over existing `fclt` behavior.
+   - Keep the CLI and canonical `.ai` roots as the source of truth.
+   - Gate high-risk global changes behind explicit review.
+   - Bundle agent-facing skills for work units, writeback, evolution, capability search, and automation setup.
+
+8. Tighten selector consistency.
    - Use one selector grammar across `list`, `show`, `graph`, `enable`, `disable`, `trust`, `audit`, writeback, and evolution.
    - Return useful ambiguity errors with candidates.
 

package/docs/security-trust.md

@@ -0,0 +1,89 @@
+# Security and Trust
+
+`fclt` can inspect and install capability that affects agent behavior. Treat that capability like code.
+
+## Source Trust
+
+Remote catalogs can be useful, but they should not become trusted by accident.
+
+```bash
+fclt sources list
+fclt verify-source skills.sh --json
+fclt sources trust skills.sh --note "reviewed"
+fclt install skills.sh:code-review --as code-review-skills-sh --strict-source-trust
+```
+
+Source trust has three practical states:
+
+- `trusted`: reviewed source, eligible for strict installs and updates
+- `review`: visible but not trusted for strict installs
+- `blocked`: not eligible for install/update
+
+## Item Trust
+
+Individual skills and MCP servers can also be trusted or untrusted:
+
+```bash
+fclt trust <skill-name>
+fclt trust mcp:<name>
+fclt untrust <skill-name>
+fclt untrust mcp:<name>
+fclt trust skills --all
+fclt untrust mcp --all
+```
+
+Use item trust when a source contains mixed-quality skills or MCP servers, or when local review happens item by item.
+
+## Audit
+
+Run an interactive audit:
+
+```bash
+fclt audit
+```
+
+Run static checks in automation:
+
+```bash
+fclt audit --non-interactive --severity high
+fclt audit --non-interactive mcp:github --severity medium --json
+```
+
+Suppress or fix reviewed findings:
+
+```bash
+fclt audit safe mcp:github --rule static:mcp-env-inline-secret --note "reviewed"
+fclt audit fix mcp:github
+```
+
+## Secrets
+
+Tracked canonical MCP config should not inline secrets. Put machine-specific values in ignored local overlays:
+
+```text
+~/.ai/mcp/servers.local.json
+<repo>/.ai/mcp/servers.local.json
+```
+
+`inventory --json` redacts MCP secrets by default. Use `--show-secrets` only for local debugging.
+
+## Commit Hygiene
+
+Commit canonical source that should travel:
+
+- instructions
+- snippets
+- skills
+- agents
+- MCP definitions without secrets
+- project sync policy
+
+Do not commit:
+
+- generated index or graph state
+- machine-local writeback queues
+- proposal metadata and draft patches
+- rendered tool outputs
+- local secret overlays
+
+Project-scoped writebacks and evolution proposals are mirrored for review under global `~/.ai/writebacks/projects/<slug-hash>/` and `~/.ai/evolution/projects/<slug-hash>/`, not under repo-local `<repo>/.ai`.

package/docs/writeback-evolution.md

@@ -1,7 +1,9 @@
-# Writeback And Evolution
+# Writeback and Evolution
 
 Writeback preserves useful signal from real work. Evolution turns repeated signal into reviewable changes.
 
+Use this when normal work exposes the same problem more than once: shallow tests, missing context, stale guidance, a slow tool path, or a missing skill. Ignore it for one-off preferences and vague complaints.
+
 Use this loop when a task exposes durable friction:
 
 1. record one targeted writeback
@@ -77,7 +79,7 @@ fclt ai evolve promote EV-00003 --to global --project
 
 ## Review Artifacts
 
-Runtime JSON queues, proposal metadata, draft patches, and journals stay in machine-local Facult state.
+Runtime JSON queues, proposal metadata, draft patches, and journals stay in machine-local `fclt` state.
 
 Human-readable Markdown mirrors live under global `~/.ai`:
 
@@ -95,3 +97,9 @@ Project-scoped artifacts include project metadata in frontmatter. They do not ge
 Global instructions, skills, plugins, and other high-risk shared surfaces require explicit review before apply. Project-scoped additive markdown changes can be lower risk, but still need evidence and a clear target.
 
 Executable product or tooling work belongs in the task system. Use evolution for the reusable instruction, skill, prompt, or operating-model change that should survive that work.
+
+## Next
+
+- Read [Composable Capability](./composable-capability.md) to choose the smallest target.
+- Read [Automations](./automations.md) to schedule recurring review loops.
+- Read [Security and trust](./security-trust.md) before applying global changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "Manage canonical AI capabilities, sync surfaces, and evolution state.",
   "type": "module",
   "license": "MIT",
@@ -32,6 +32,7 @@
     "bin/fclt.cjs",
     "bin/facult.cjs",
     "docs/**/*.md",
+    "docs/**/*.png",
     "src/**/*.ts",
     "!src/**/*.test.ts",
     "README.md",