facult 2.10.0 → 2.11.0

package/README.md

@@ -13,9 +13,6 @@
   <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>
 
 <p align="center">
@@ -118,6 +115,13 @@ fclt templates init project-ai
 fclt index
 ```
 
+If you want a concrete copy of the built-in operating-model pack without managing a tool:
+
+```bash
+fclt templates init operating-model --global
+fclt templates init operating-model --root /path/to/.ai
+```
+
 ### 3. Import existing skills or config
 
 ```bash
@@ -206,14 +210,27 @@ Useful AI behavior is composable. You need small reusable parts, a clean way to
 
 The renderer is optional. The low-friction default is to let tools keep their native files, use `fclt inventory`/`scan`/`list` to see the full global set, and use `fclt consolidate` or `fclt sync --adopt-live` only when you explicitly want to promote live tool edits into canonical `~/.ai`.
 
+## Documentation
+
+Focused docs live under [docs](./docs/README.md):
+
+- [Concepts](./docs/concepts.md): roots, scopes, state layers, and asset types
+- [Managed Mode](./docs/managed-mode.md): safe rendering and adoption rules
+- [Project `.ai`](./docs/project-ai.md): repo-local capability and project sync policy
+- [Built-In Pack](./docs/built-in-pack.md): packaged writeback/evolution defaults
+- [Writeback And Evolution](./docs/writeback-evolution.md): feedback-loop workflow and review surfaces
+- [Roadmap](./docs/roadmap.md): current gaps and non-goals
+
 ## Built-in Defaults
 
 `fclt` includes a built-in layer for writeback and evolution. By default, that layer provides:
-- instructions for learning/writeback, evolution, integration, and project capability
+- instructions for work units, learning/writeback, evolution, integration, and project capability
 - agents such as `writeback-curator`, `evolution-planner`, and `scope-promoter`
 - skills such as `capability-evolution` and `project-operating-layer-design`
 
-Those 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, so every managed agent sees that it can preserve strong friction with `fclt ai writeback ...` and escalate repeated signal with `fclt ai evolve ...`. Project-local `.ai` roots do not sync the built-in operating-model layer unless you explicitly enable it.
+Those built-in defaults are always available as `@builtin/facult-operating-model/...`. To install a concrete copy into a canonical root without managing any tool, run `fclt templates init operating-model --global`, `--project`, or `--root /path/to/.ai`.
+
+Managed mode is separate. Global tool management renders the bundled docs, agents, and skills into that tool's live files, so every managed agent sees that it can preserve strong friction with `fclt ai writeback ...` and escalate repeated signal with `fclt ai evolve ...`. Project-local `.ai` roots do not sync the built-in operating-model layer unless you explicitly enable it.
 
 The intended feedback loop is:
 1. agents notice durable friction, weak verification, stale guidance, or missing capability during normal work
@@ -238,9 +255,10 @@ Put that in `config.toml` or `config.local.toml` under the active canonical root
 `fclt` is CLI-first. The practical setup is:
 1. Install `fclt` globally so any agent runtime can execute it.
 2. Use `fclt inventory`, `fclt list`, and `fclt consolidate` to inspect and normalize existing tool-native state.
-3. If you want fclt-owned rendered outputs, manage each agent tool with `fclt manage <tool>` and `fclt sync`.
-4. Let the built-in operating-model layer render global writeback/evolution instructions into the tool only where managed rendering is worth the ownership tradeoff.
-5. Optionally scaffold MCP wrappers if you want an MCP entry that delegates to `fclt`.
+3. Install the built-in operating-model pack into `~/.ai` or a project `.ai` when you want editable canonical defaults without managed rendering.
+4. If you want fclt-owned rendered outputs, manage each agent tool with `fclt manage <tool>` and `fclt sync`.
+5. Let the built-in operating-model layer render global writeback/evolution instructions into the tool only where managed rendering is worth the ownership tradeoff.
+6. Optionally scaffold MCP wrappers if you want an MCP entry that delegates to `fclt`.
 
 ```bash
 # Scaffold reusable templates in the canonical store
@@ -269,7 +287,7 @@ The supported review surface today is the CLI plus generated Codex automation te
 
 ## Mental Model
 
-`fclt` treats both `~/.ai` and `<repo>/.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.
+`fclt` treats both `~/.ai` and `<repo>/.ai` as canonical stores. The global store is for user-owned reusable capability. The project store is for repo-owned capability that should travel with the codebase.
 
 Typical layout:
 
@@ -622,6 +640,7 @@ fclt sources clear <source>
 - Templates and snippets
 ```bash
 fclt templates list
+fclt templates init operating-model [--global|--project|--root PATH] [--force] [--dry-run]
 fclt templates init project-ai
 fclt templates init skill <name>
 fclt templates init mcp <name>
@@ -849,7 +868,7 @@ Not as a first-party `fclt mcp serve` runtime.
 ### Does fclt now manage global AI config, not just skills and MCP?
 
 Yes. The core model now includes:
-- canonical personal AI source in `~/.ai`
+- canonical user-owned AI source in `~/.ai`
 - rendered managed outputs in tool homes such as `~/.codex`, `~/.agents`, and `~/plugins`
 - global instruction docs such as `AGENTS.global.md`, rendered by default into `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, and `~/.cursor/AGENTS.md`
 - Codex-authored skills in `~/.agents/skills`

package/assets/packs/facult-operating-model/AGENTS.global.md

@@ -4,6 +4,7 @@ This machine has a default Facult operating-model layer available.
 
 When work produces durable friction, weak verification, stale guidance, or a missing skill/tool capability, preserve that signal with `fclt ai writeback ...` when the target and scope are clear. When repeated writebacks or clearly missing capability point at a concrete improvement, use `fclt ai evolve ...` or the `capability-evolution` skill to make a reviewable proposal.
 
+For work-unit framing, read `@builtin/facult-operating-model/instructions/WORK_UNITS.md`.
 For writeback and evolution, read `@builtin/facult-operating-model/instructions/EVOLUTION.md`.
 For learning and writeback defaults, read `@builtin/facult-operating-model/instructions/LEARNING_AND_WRITEBACK.md`.
 For deciding whether capability belongs in global or project scope, read `@builtin/facult-operating-model/instructions/PROJECT_CAPABILITY.md`.

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

@@ -129,6 +129,6 @@ Use the smallest durable change that fits the evidence.
 - prefer the smallest safe change
 - keep reviewable evidence tied to source writebacks
 - do not globalize project behavior too early
-- do not apply high-risk global instruction, skill, plugin, or non-COS changes without explicit review/approval
+- do not apply high-risk global instruction, skill, plugin, or shared-tool changes without explicit review/approval
 
 Apply is for markdown canonical assets only. If the target is wrong, revise the proposal rather than forcing it through.

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

@@ -0,0 +1,61 @@
+---
+description: "Define work units so agent tasks have a clear goal, evidence path, artifact, and writeback target."
+tags: ["work-units", "planning", "verification", "writeback"]
+---
+
+# Work Units
+
+A work unit is the smallest coherent unit of agent work that can be understood, verified, and preserved.
+
+It is not just the user's latest sentence. It is the operational shape around that sentence: what is being changed, why it matters, what evidence is needed, what artifact should remain, and how future agents should benefit from the result.
+
+## Minimum Contract
+
+A well-formed work unit names:
+
+- goal: the outcome the user needs
+- acceptance criteria: what must be true when the work is done
+- required context: source files, docs, systems, messages, or prior decisions needed for correctness
+- constraints: permissions, privacy, compatibility, deadlines, ownership, or scope limits
+- signals or evidence: checks that can confirm progress or falsify assumptions
+- output artifact: code, docs, proposal, issue, note, draft, or report
+- verification path: commands, review surfaces, manual checks, or source-of-truth reads
+- writeback target: where durable learning belongs if the work teaches something reusable
+
+If one of these is missing and the gap blocks correctness, surface the gap early and recover it before moving faster.
+
+## Why It Exists
+
+Work-unit framing prevents shallow completion. It helps agents avoid:
+
+- changing files before understanding the target
+- treating a weak green signal as proof
+- losing reusable learning in chat
+- creating duplicate tasks or proposals
+- turning one-off preferences into global rules
+- pushing project-specific details into global capability
+
+## How To Use It
+
+For simple tasks, keep the work unit implicit but still verify the result.
+
+For ambiguous, high-impact, or multi-step tasks, make the work unit explicit before executing. A compact form is enough:
+
+```text
+Goal:
+Acceptance:
+Context:
+Constraints:
+Evidence:
+Artifact:
+Verification:
+Writeback:
+```
+
+Use the smallest framing that makes the task correct. Do not turn every request into paperwork.
+
+## Writeback
+
+When the work reveals durable friction, missing capability, stale guidance, or a repeatable workflow, prefer one strong writeback over many weak ones.
+
+Use `fclt ai writeback add ...` when the target asset, scope, and evidence are clear. Use `fclt ai evolve ...` only when repeated signal supports a concrete proposal.

package/docs/README.md

@@ -0,0 +1,18 @@
+# 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.
+
+Start here:
+
+- [Concepts](./concepts.md): canonical roots, generated state, rendered outputs, scopes, and asset types.
+- [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.
+
+## Documentation Policy
+
+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`.
+
+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.

package/docs/built-in-pack.md

@@ -0,0 +1,91 @@
+# Built-In Pack
+
+`fclt` ships an operating-model pack:
+
+```text
+assets/packs/facult-operating-model/
+```
+
+It provides a default feedback loop for agents that use `fclt`.
+
+## Included Assets
+
+Instructions:
+
+- `WORK_UNITS.md`
+- `LEARNING_AND_WRITEBACK.md`
+- `EVOLUTION.md`
+- `PROJECT_CAPABILITY.md`
+- `INTEGRATION.md`
+
+Skills:
+
+- `capability-evolution`
+- `project-operating-layer-design`
+
+Agents:
+
+- `writeback-curator`
+- `evolution-planner`
+- `scope-promoter`
+- `integration-auditor`
+
+Global doc:
+
+- `AGENTS.global.md`
+
+## When It Becomes Active
+
+The built-in pack is always available as a built-in source:
+
+```text
+@builtin/facult-operating-model/...
+```
+
+Install a concrete copy into a canonical root without managing any tool:
+
+```bash
+fclt templates init operating-model --global
+fclt templates init operating-model --project
+fclt templates init operating-model --root /path/to/.ai
+```
+
+That writes the pack into the selected `.ai` root and rebuilds its index. It does not render files into Codex, Claude, or any other tool home.
+
+Use `project-ai` when the target is the current repo:
+
+```bash
+cd /path/to/repo
+fclt templates init project-ai
+```
+
+Managed mode is only the rendering layer. The pack becomes live tool guidance when you manage a tool and sync:
+
+```bash
+fclt manage codex
+fclt sync codex
+```
+
+Global managed tools receive the built-in writeback/evolution guidance by default. Project-local `.ai` roots do not render the built-in operating model into repo-local tool outputs unless project sync policy explicitly allows it. Installing the pack and rendering it into a tool are separate decisions.
+
+Disable built-in default sync for a canonical root:
+
+```toml
+version = 1
+
+[builtin]
+sync_defaults = false
+```
+
+## Design Rule
+
+The built-in pack should stay small. It should teach:
+
+- work-unit discipline
+- verification
+- writeback
+- evolution proposal review
+- 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.

package/docs/concepts.md

@@ -0,0 +1,123 @@
+# Concepts
+
+`fclt` keeps AI capability in a canonical store, lets you inspect it, and optionally renders approved pieces into tool-native files.
+
+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.
+
+## Roots And Scopes
+
+Global root:
+
+```text
+~/.ai/
+```
+
+Use this for user-owned reusable capability: shared instructions, snippets, skills, agents, MCP definitions, and writeback/evolution review artifacts.
+
+Project root:
+
+```text
+<repo>/.ai/
+```
+
+Use this for repo-owned capability that should travel with the codebase: project instructions, project skills, project MCP definitions, and project sync policy.
+
+Built-in root:
+
+```text
+@builtin/facult-operating-model/...
+```
+
+Use this for packaged defaults shipped with `fclt`.
+
+Remote sources:
+
+```text
+skills.sh:<name>
+smithery:<name>
+glama:<name>
+```
+
+Use these as installable catalog sources. Review and trust source policy before installing remote capability broadly.
+
+## Work Units
+
+A work unit is a scoped agent task with a goal, acceptance criteria, required context, constraints, evidence, output artifact, verification path, and writeback target.
+
+Agents should keep this implicit for simple work and make it explicit when the task is ambiguous, risky, or multi-step. The built-in operating-model pack includes `WORK_UNITS.md` so managed agents and canonical `.ai` roots can share the same framing.
+
+## State Layers
+
+Canonical source is edited by humans or accepted proposals.
+
+Examples:
+
+```text
+~/.ai/instructions/VERIFICATION.md
+<repo>/.ai/skills/project-review/SKILL.md
+```
+
+Generated state is rebuildable.
+
+Examples:
+
+```text
+~/.ai/.facult/ai/index.json
+~/.ai/.facult/ai/graph.json
+```
+
+Project generated state lives in machine-local Facult state, not in the repo.
+
+Machine runtime state records local behavior and history.
+
+Examples:
+
+```text
+~/Library/Application Support/fclt/global/managed.json
+~/Library/Application Support/fclt/projects/<slug-hash>/managed.json
+```
+
+Rendered outputs are files consumed by tools.
+
+Examples:
+
+```text
+~/.codex/AGENTS.md
+~/.agents/skills/<name>
+<repo>/.codex/agents/<name>.toml
+```
+
+Review artifacts are Markdown mirrors for human review.
+
+Examples:
+
+```text
+~/.ai/writebacks/global/WB-00001.md
+~/.ai/evolution/projects/<slug-hash>/EV-00001.md
+```
+
+## Asset Types
+
+Common canonical asset types:
+
+- instructions: reusable markdown guidance
+- snippets: composable markdown partials
+- skills: workflow-specific folders with `SKILL.md`
+- agents: role manifests
+- MCP servers: canonical MCP definitions
+- tool config and rules: tool-specific defaults
+- automations: scheduled review or maintenance prompts
+- plugins: local tool plugin bundles and marketplaces
+
+Not every asset must be rendered into every tool. Use inventory and policy first, then managed sync only where `fclt` should own the rendered output.
+
+## Feedback Loop
+
+The durable loop is:
+
+1. Inspect live tool and project state.
+2. Record strong writebacks when real work exposes reusable friction or missing capability.
+3. Group repeated writebacks.
+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.

package/docs/managed-mode.md

@@ -0,0 +1,73 @@
+# 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.
+
+Prefer this default workflow:
+
+```bash
+fclt status
+fclt inventory --json
+fclt list skills
+fclt consolidate --auto keep-current --from ~/.codex/skills --from ~/.agents/skills
+```
+
+Use managed mode only after that:
+
+```bash
+fclt manage codex --dry-run
+fclt manage codex --adopt-existing
+fclt sync codex --dry-run
+fclt sync codex
+```
+
+## Adoption Commands
+
+`manage --adopt-existing` is for entering managed mode. It imports existing tool-native content into the canonical store before `fclt` starts writing that tool surface.
+
+`sync --adopt-live` is for intentional later promotion. It imports live tool edits into canonical state before rendering.
+
+Ordinary `fclt sync` does not adopt live tool edits. This lets Codex, Claude, Cursor, or another tool keep local edits without `fclt` silently claiming ownership.
+
+## Conflict Behavior
+
+When live content differs from canonical content:
+
+- default `sync` preserves the live file and tells you to rerun with `--adopt-live` if you want promotion
+- `sync --adopt-live` imports the live content into canonical source where supported
+- 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.
+
+## Project Managed Mode
+
+Project sync is default-deny. A project `.ai` root can exist without rendering anything into repo-local tool outputs.
+
+Allow project assets explicitly:
+
+```toml
+version = 1
+
+[project_sync.codex]
+skills = ["project-review"]
+agents = ["review-operator"]
+automations = ["project-check"]
+mcp_servers = ["github"]
+global_docs = true
+tool_rules = true
+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
+
+Do not use managed mode when:
+
+- you only need discovery or inventory
+- another tool should remain the owner of its files
+- a repo has no clear project sync policy
+- the canonical source is missing
+- you are debugging and need read-only evidence first
+
+Use `fclt inventory`, `scan`, `list`, `show`, `graph`, `status`, and `audit` instead.

package/docs/project-ai.md

@@ -0,0 +1,91 @@
+# 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.
+
+Create one with:
+
+```bash
+cd /path/to/repo
+fclt templates init project-ai
+fclt index --project
+fclt status --project
+```
+
+Typical layout:
+
+```text
+<repo>/.ai/
+  config.toml
+  instructions/
+  snippets/
+  agents/
+  skills/
+  mcp/
+  tools/
+```
+
+## What Belongs In Project `.ai`
+
+Use project `.ai` for:
+
+- repo-specific instructions
+- project review skills
+- project MCP definitions without secrets
+- project snippets
+- project sync policy
+- canonical automation prompts that should travel with the repo
+
+Do not put these in project `.ai`:
+
+- writeback queues
+- evolution proposal metadata
+- generated index/graph state
+- local machine paths
+- 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>/`.
+
+## 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.
+
+Current behavior:
+
+```bash
+fclt status --project
+fclt sync --project --dry-run
+```
+
+`status` reports `project-generated-only`, and `sync` skips until canonical source is restored or initialized.
+
+## Project Sync Policy
+
+Project sync is default-deny. Nothing from global or project canonical source renders into repo-local managed tool outputs unless the repo opts in.
+
+Example:
+
+```toml
+version = 1
+
+[project_sync.codex]
+skills = ["project-review"]
+agents = ["review-operator"]
+mcp_servers = ["github"]
+global_docs = true
+tool_rules = true
+tool_config = true
+```
+
+This includes inherited global assets. If a global skill should appear in project-managed Codex output, list it explicitly.
+
+## Verification
+
+Use these commands after changing project `.ai`:
+
+```bash
+fclt status --project
+fclt list skills --project
+fclt graph AGENTS.global.md --project
+fclt sync codex --project --dry-run
+```

package/docs/roadmap.md

@@ -0,0 +1,56 @@
+# 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.
+
+## Already Shipped
+
+- `fclt status` with root, managed-tool, generated-state, writeback, and evolution review paths.
+- Generated-only project `.ai` detection and sync skip.
+- Machine-local project generated state.
+- Global Markdown review artifacts for writebacks and evolution proposals.
+- 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`.
+- Cleaner built-in canonical refs.
+- JSON-first `inventory`.
+- `sync --adopt-live` for explicit promotion of live tool edits.
+- Managed sync local-edit protection for rendered docs, config, MCP, and skills.
+
+## Current Priorities
+
+1. 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.
+   - Group writes, updates, removals, skips, conflicts, and repairs.
+   - Expose the same plan as JSON.
+   - Explain source refs and policy reasons.
+
+3. 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.
+   - 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.
+   - List and show them consistently.
+   - Add graph visibility.
+   - Include them in status and sync plans.
+
+6. Tighten selector consistency.
+   - Use one selector grammar across `list`, `show`, `graph`, `enable`, `disable`, `trust`, `audit`, writeback, and evolution.
+   - Return useful ambiguity errors with candidates.
+
+## Non-Goals
+
+- Do not make managed mode the default way to inspect existing AI tool state.
+- Do not store project writeback/evolution review artifacts in repo-local `.ai`.
+- Do not silently adopt live tool edits during ordinary sync.
+- Do not turn the built-in pack into a general preference archive.
+- Do not require users to inspect machine-local state files to understand normal CLI behavior.

package/docs/writeback-evolution.md

@@ -0,0 +1,97 @@
+# Writeback And Evolution
+
+Writeback preserves useful signal from real work. Evolution turns repeated signal into reviewable changes.
+
+Use this loop when a task exposes durable friction:
+
+1. record one targeted writeback
+2. group or summarize related writebacks
+3. propose only when the evidence repeats or a missing capability is obvious
+4. draft the smallest valid proposal
+5. review, accept, and apply when the change is safe
+
+## Writeback
+
+Record writeback when the signal is durable and targetable:
+
+```bash
+fclt ai writeback add \
+  --kind weak_verification \
+  --summary "Checks were too shallow" \
+  --asset instruction:VERIFICATION
+```
+
+Useful kinds:
+
+- `weak_verification`
+- `false_positive`
+- `missing_context`
+- `reusable_pattern`
+- `capability_gap`
+- `bad_default`
+
+Avoid writeback for one-off preferences, vague complaints, or speculative ideas.
+
+## Evolution
+
+Review accumulated signal:
+
+```bash
+fclt ai writeback list
+fclt ai writeback group --by asset
+fclt ai writeback summarize --by kind
+fclt ai evolve propose
+fclt ai evolve list
+```
+
+Draft and review:
+
+```bash
+fclt ai evolve draft EV-00001
+fclt ai evolve review EV-00001
+fclt ai evolve accept EV-00001
+fclt ai evolve apply EV-00001
+```
+
+Supported durable proposal kinds include:
+
+- `update_asset`
+- `create_asset`
+- `extract_snippet`
+- `add_skill`
+- `promote_asset`
+
+Use the smallest kind that solves the repeated problem.
+
+## Scope
+
+Use project scope for repo-specific tooling, tests, architecture, and workflows.
+
+Use global scope for shared doctrine, reusable skills, shared agents, or cross-project capability gaps.
+
+Promote project proposals to global only after repeated reuse:
+
+```bash
+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.
+
+Human-readable Markdown mirrors live under global `~/.ai`:
+
+```text
+~/.ai/writebacks/global/
+~/.ai/writebacks/projects/<slug-hash>/
+~/.ai/evolution/global/
+~/.ai/evolution/projects/<slug-hash>/
+```
+
+Project-scoped artifacts include project metadata in frontmatter. They do not get written into repo-local `<repo>/.ai/writebacks` or `<repo>/.ai/evolution`.
+
+## Approval Rule
+
+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.

package/package.json

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

package/src/builtin-assets.ts

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-builtin-assets.ts. Do not edit by hand.
 
 export const BUILTIN_OPERATING_MODEL_FILES = JSON.parse(
-  '{"AGENTS.global.md":"# Facult Operating Defaults\\n\\nThis machine has a default Facult operating-model layer available.\\n\\nWhen work produces durable friction, weak verification, stale guidance, or a missing skill/tool capability, preserve that signal with `fclt ai writeback ...` when the target and scope are clear. When repeated writebacks or clearly missing capability point at a concrete improvement, use `fclt ai evolve ...` or the `capability-evolution` skill to make a reviewable proposal.\\n\\nFor writeback and evolution, read `@builtin/facult-operating-model/instructions/EVOLUTION.md`.\\nFor learning and writeback defaults, read `@builtin/facult-operating-model/instructions/LEARNING_AND_WRITEBACK.md`.\\nFor deciding whether capability belongs in global or project scope, read `@builtin/facult-operating-model/instructions/PROJECT_CAPABILITY.md`.\\nFor project operating-layer design, read `@builtin/facult-operating-model/instructions/INTEGRATION.md`.\\n\\nBuiltin specialist agents are available for:\\n- writeback curation\\n- evolution planning\\n- scope promotion\\n- integration auditing\\n\\nBuiltin skills are available for:\\n- capability evolution\\n- project operating-layer design\\n","agents/evolution-planner/agent.toml":"name = \\"evolution-planner\\"\\ndescription = \\"Turn repeated writeback into concrete capability proposals.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou plan capability evolution.\\n\\nPrioritize:\\n- smallest useful change\\n- correct target asset type\\n- correct target scope\\n- evidence that justifies the change\\n- repeated writeback clusters or clearly missing capabilities, not isolated preferences\\n\\nProposal kinds you should consider first:\\n- update_asset\\n- create_asset\\n- extract_snippet\\n- add_skill\\n- promote_asset\\n\\nDefault to project scope when the pattern is repo-local.\\nPromote to global only when reuse is demonstrated and pollution risk is low.\\n\\nReturn concise proposals ordered by expected leverage, including:\\n- proposal kind\\n- target asset\\n- target scope\\n- why this is the smallest durable change\\n\\nDo not escalate to evolution when a single writeback is enough.\\nDo not use evolution as a substitute for executable task tracking when the main need is owner, priority, state, or implementation follow-through.\\n\\"\\"\\"\\n","agents/integration-auditor/agent.toml":"name = \\"integration-auditor\\"\\ndescription = \\"Find where local success can still fail system-wide.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou audit integration risk.\\n\\nPrioritize:\\n- hidden dependencies\\n- rollout hazards\\n- operational constraints\\n- gaps between local verification and real system behavior\\n\\nReturn concise findings ordered by impact.\\n\\"\\"\\"\\n","agents/scope-promoter/agent.toml":"name = \\"scope-promoter\\"\\ndescription = \\"Decide whether learning belongs at project or global scope.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou decide scope.\\n\\nPrioritize:\\n- project specificity\\n- cross-project reuse potential\\n- pollution risk from globalizing too early\\n\\nWhen recommending promotion, make the standard path explicit:\\n- keep the source capability in project scope until promotion is approved\\n- create a reviewable global proposal\\n- do not treat promotion as implicit apply\\n\\nReturn concise decisions with rationale.\\n\\"\\"\\"\\n","agents/writeback-curator/agent.toml":"name = \\"writeback-curator\\"\\ndescription = \\"Turn noisy outcomes into high-signal writeback.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou curate durable writeback.\\n\\nPrioritize:\\n- repeated failures\\n- repeated wins\\n- stale guidance\\n- missing capability edges\\n- tool, skill, MCP, plugin, automation, or instruction friction that repeatedly slows work down\\n\\nFor each recommendation, prefer returning:\\n- suggested writeback kind\\n- best target asset or destination\\n- best scope (`project` or `global`)\\n- the evidence that justifies recording it\\n\\nDo not emit low-signal noise.\\nIf the learning is repo-specific, keep it project-scoped by default.\\nWhen the signal is already strong and the target is clear, prefer recommending direct writeback capture rather than abstract advice.\\nWhen the issue is executable tooling work, recommend task tracking for the fix and writeback only for the reusable operating-model learning.\\n\\"\\"\\"\\n","instructions/EVOLUTION.md":"---\\ndescription: Turn repeated signal into concrete capability changes.\\ntags: [facult, evolution, writeback]\\n---\\n\\n# Evolution\\n\\nUse writeback and evolution to improve the AI operating layer itself.\\n\\nEvolution is the synthesis and change side of the feedback loop. It turns accumulated writebacks, repeated tool friction, stale canonical assets, or clearly missing capability into small reviewable changes to instructions, skills, snippets, agents, or other markdown canonical assets.\\n\\n## When To Record Writeback\\n\\nRecord writeback when one of these is true:\\n\\n- the same failure repeats\\n- the same success pattern repeats\\n- guidance is stale or missing\\n- a prompt or loop has to be restated often\\n- a project-specific pattern looks reusable\\n\\nDo not record low-signal noise:\\n\\n- one-off annoyance with no reuse value\\n- generic \\"could be better\\" commentary\\n- duplicate observations with no new evidence\\n\\nThe intended default is that agents record strong writebacks themselves when the signal is clear enough, rather than only recommending that a user do it manually later.\\n\\nDo not wait for a weekly review to preserve high-signal evidence. Do wait for repeated evidence or a clearly missing capability before drafting a proposal.\\n\\n## Scope\\n\\nChoose `project` scope when the learning depends on:\\n\\n- repo architecture\\n- team workflow\\n- project tooling\\n- local testing or verification behavior\\n\\nChoose `global` scope when the learning is reusable across projects.\\n\\nPromote from project to global only after repeated reuse or strong evidence.\\n\\n## Writeback Kinds\\n\\nCommon kinds:\\n\\n- `weak_verification`\\n- `false_positive`\\n- `missing_context`\\n- `reusable_pattern`\\n- `capability_gap`\\n- `bad_default`\\n\\nEvery good writeback should try to include:\\n\\n- a concrete summary\\n- the best target asset if known\\n- the right scope\\n- domain or tags when useful\\n\\n## Operator Flow\\n\\nTypical workflow:\\n\\n```bash\\nfclt ai writeback add --kind weak_verification --summary \\"Checks were too shallow\\" --asset instruction:VERIFICATION\\nfclt ai writeback group --by asset\\nfclt ai writeback summarize --by domain\\nfclt ai evolve propose\\nfclt ai evolve draft EV-00001\\nfclt ai evolve accept EV-00001\\nfclt ai evolve apply EV-00001\\n```\\n\\nUse `fclt ai evolve draft <id> --append \\"...\\"` to revise a draft while preserving draft history.\\n\\nReview surfaces:\\n\\n- open `~/.ai/writebacks/` and `~/.ai/evolution/` in a Markdown editor for frontmatter-rich global and project-scoped review artifacts\\n- `fclt status --json` for queue/proposal paths, review artifact paths, counts, and active scope\\n- `fclt ai writeback list|show|group|summarize` for raw and clustered signal\\n- `fclt ai evolve list|show|review` for proposal state without applying changes\\n- `fclt templates init automation learning-review` for recurring capture/review\\n- `fclt templates init automation evolution-review` for recurring proposal review\\n- `fclt templates init automation tool-call-audit` for repeated tool-friction review\\n\\nEvolution proposal metadata, markdown drafts, patch artifacts, writeback queues,\\nand journals are runtime state. `fclt` stores JSON queues, proposal records,\\ndraft refs, patches, and journals in machine-local Facult state. It mirrors\\nhuman-readable review artifacts into global `~/.ai/writebacks/...` and\\n`~/.ai/evolution/...`, including project-scoped artifacts under\\n`projects/<slug-hash>/` with cwd/project metadata in frontmatter. Canonical\\nassets in `~/.ai` or `<repo>/.ai` should only change when a proposal is applied.\\n\\n## Default Agent Behavior\\n\\nUse the smallest action that fits the signal:\\n\\n1. record one strong writeback when there is a clear durable learning\\n2. use `writeback-curator` when the target, kind, or scope is ambiguous\\n3. use `capability-evolution` or `evolution-planner` when repeated signal should become a proposal\\n4. do not draft or apply proposals just because a writeback exists; require repeated evidence or a clearly missing capability\\n\\nAvoid creating writeback/evolution noise for one-off nits, vague preferences, or speculative ideas without evidence.\\n\\nWhen the friction is executable product/tooling work that needs ownership,\\npriority, state, or implementation follow-through, create or update a real task\\nsystem item instead of forcing it into capability evolution. Use evolution for\\nthe reusable operating-layer change.\\n\\n## Proposal Kinds\\n\\nCurrent supported proposal kinds:\\n\\n- `update_asset`\\n- `create_asset`\\n- `extract_snippet`\\n- `add_skill`\\n- `promote_asset`\\n\\nUse the smallest durable change that fits the evidence.\\n\\n## Review And Apply Rules\\n\\n- draft before apply\\n- accept before apply\\n- prefer the smallest safe change\\n- keep reviewable evidence tied to source writebacks\\n- do not globalize project behavior too early\\n- do not apply high-risk global instruction, skill, plugin, or non-COS changes without explicit review/approval\\n\\nApply is for markdown canonical assets only. If the target is wrong, revise the proposal rather than forcing it through.\\n","instructions/INTEGRATION.md":"---\\ndescription: Detect where local success can still fail at integration boundaries.\\ntags: [facult, integration, verification]\\n---\\n\\n# Integration\\n\\nDistinguish local correctness from system correctness. Check hidden dependencies, rollout order, and operational constraints before calling work done.\\n","instructions/LEARNING_AND_WRITEBACK.md":"---\\ndescription: Preserve durable signal and record writeback when the operating layer should learn.\\ntags: [facult, learning, writeback]\\n---\\n\\n# Learning And Writeback\\n\\nUse this when work produces a durable decision, failure, success pattern, or missing guardrail that should outlive the current task.\\n\\nThis is the capture side of the feedback loop. The goal is to let normal agent work produce reusable signal without requiring a human to manually restate every friction point later.\\n\\n## Default Behavior\\n\\nThe normal path should be agent-driven.\\n\\nIf you can clearly answer:\\n\\n- what was learned\\n- why it matters\\n- where it should land\\n- whether it belongs in `project` or `global`\\n\\nthen record the writeback instead of only suggesting that someone should do it later.\\n\\nUse:\\n\\n```bash\\nfclt ai writeback add --kind <kind> --summary \\"<summary>\\" --asset <asset-selector>\\n```\\n\\nThe writeback queue is runtime state, not canonical source. `fclt` stores JSON\\nqueue state in machine-local Facult state so sandboxed agents can record durable\\nfriction without mutating canonical assets unless an evolution proposal is later\\nreviewed and applied.\\n\\nEvery writeback also refreshes a Markdown review artifact under the global\\n`~/.ai/writebacks/...` tree. Global signal lands in `~/.ai/writebacks/global/`;\\nproject-scoped signal lands in `~/.ai/writebacks/projects/<slug-hash>/` with\\nfrontmatter for scope, project root, cwd, target asset, status, tags, evidence,\\nand timestamps. Do not write writeback review artifacts into a repo-local `.ai`;\\nrepo-local state should contribute project metadata and evidence, not bundled\\nprivate review files.\\n\\nProject-scoped writebacks should usually be recorded from the repo that produced\\nthe evidence. Global writebacks should be reserved for shared doctrine, shared\\nskills, shared agents, tool behavior, or cross-project capability gaps.\\n\\n## Record Writeback When\\n\\n- the same failure or weak loop appears again\\n- a reusable success pattern shows up\\n- guidance is clearly stale or missing\\n- a repo-local behavior probably belongs in project capability\\n- a cross-project behavior probably belongs in global capability\\n- a skill, tool, MCP, plugin, automation, or instruction gap repeatedly slows work down\\n- an agent has to restate the same workaround, verification rule, or review rule\\n\\n## Do Not Record Writeback For\\n\\n- one-off annoyance with no durable value\\n- weak commentary with no target\\n- speculative ideas without evidence\\n- duplicate noise with no new signal\\n\\n## Follow Through\\n\\n- prefer one strong writeback over many weak ones\\n- mention the writeback id when summarizing what changed\\n- escalate to `capability-evolution` or `fclt ai evolve ...` only when the signal is repeated or clearly points at a durable capability change\\n- use `fclt ai writeback group --by asset` or `fclt ai writeback summarize --by domain` to review accumulated signal before proposing broad changes\\n- use scheduled `learning-review`, `evolution-review`, or `tool-call-audit` automations when the signal should be reviewed in the background\\n","instructions/PROJECT_CAPABILITY.md":"---\\ndescription: Decide what belongs in repo-local .ai versus the global store.\\ntags: [facult, project, scope]\\n---\\n\\n# Project Capability\\n\\nPrefer project scope when the guidance depends on repo architecture, team workflow, or colocated tooling. Promote to global only after repeated cross-project reuse.\\n\\n## Project First\\n\\nDefault to `<repo>/.ai` when the capability is about:\\n\\n- local architecture\\n- repo-specific testing or verification\\n- team conventions\\n- project tools and workflows\\n\\n## Promote Carefully\\n\\nPromote to `~/.ai` only when:\\n\\n- the same pattern succeeds in more than one repo\\n- the capability is not coupled to local architecture\\n- the global version will not create noise for unrelated projects\\n\\nUse:\\n\\n```bash\\nfclt ai evolve promote EV-00001 --to global --project\\n```\\n\\nThat creates a new global proposal for review. It does not auto-apply the promotion.\\n","skills/capability-evolution/SKILL.md":"---\\ndescription: Convert repeated writeback into concrete fclt capability proposals.\\ntags: [facult, evolution, writeback]\\n---\\n\\n# capability-evolution\\n\\n## When To Use\\nUse this skill when the same missing guidance, weak loop, or recurring win appears often enough that the AI system itself should probably change.\\n\\nDo not wait for a human operator by default if the signal is already clear and the environment permits local AI runtime state to be updated.\\n\\nUse writeback first when the signal is useful but not yet repeated. Use evolution when accumulated writebacks, repeated tool friction, or a clearly missing capability point at a specific target asset or new capability.\\n\\n## Scope Decision\\n\\nChoose `project` when the behavior depends on repo-local architecture or workflow.\\n\\nChoose `global` when the behavior is broadly reusable.\\n\\nIf unsure, start at project scope and promote later with evidence.\\n\\n## Working Flow\\n\\n1. record the strongest writeback\\n2. group or summarize repeated signal\\n3. choose the smallest valid proposal kind\\n4. draft the proposal\\n5. accept only after the target and scope are correct\\n6. apply only when the markdown target is the intended canonical asset\\n\\nUse:\\n\\n```bash\\nfclt ai writeback add ...\\nfclt ai writeback group --by asset\\nfclt ai writeback summarize --by domain\\nfclt ai evolve propose\\nfclt ai evolve draft EV-00001\\nfclt ai evolve draft EV-00001 --append \\"tighten the rule with a concrete verification step\\"\\nfclt ai evolve accept EV-00001\\nfclt ai evolve apply EV-00001\\n```\\n\\nFor background review loops, use:\\n\\n```bash\\nfclt templates init automation learning-review\\nfclt templates init automation evolution-review\\nfclt templates init automation tool-call-audit\\n```\\n\\nIf there is not yet enough repeated signal for evolution, record the writeback and stop there.\\n\\n## Proposal Kind Selection\\n\\n- `update_asset` for tightening existing guidance\\n- `create_asset` for missing instructions or docs\\n- `extract_snippet` for reusable partial guidance\\n- `add_skill` for reusable workflow instruction\\n- `promote_asset` for project-to-global promotion\\n\\nUse task tracking instead of evolution when the main work is an executable tool or product fix that needs an owner, priority, state, or delivery plan. Use evolution for the reusable instruction, skill, or operating-model change that should survive that fix.\\n\\n## Output Contract\\n- repeated signal\\n- proposed asset change\\n- target scope\\n- evidence\\n- smallest useful next step\\n","skills/project-operating-layer-design/SKILL.md":"---\\ndescription: Design or improve a repo-local .ai operating layer.\\ntags: [facult, project, design]\\n---\\n\\n# project-operating-layer-design\\n\\n## When To Use\\nUse this skill when a project needs its own `.ai/` structure, repo-specific instructions, or local bootstrap guidance.\\n\\n## Output Contract\\n- recommended `.ai/` layout\\n- what stays project-local\\n- what stays global\\n- what should remain generated runtime output only\\n"}'
+  '{"AGENTS.global.md":"# Facult Operating Defaults\\n\\nThis machine has a default Facult operating-model layer available.\\n\\nWhen work produces durable friction, weak verification, stale guidance, or a missing skill/tool capability, preserve that signal with `fclt ai writeback ...` when the target and scope are clear. When repeated writebacks or clearly missing capability point at a concrete improvement, use `fclt ai evolve ...` or the `capability-evolution` skill to make a reviewable proposal.\\n\\nFor work-unit framing, read `@builtin/facult-operating-model/instructions/WORK_UNITS.md`.\\nFor writeback and evolution, read `@builtin/facult-operating-model/instructions/EVOLUTION.md`.\\nFor learning and writeback defaults, read `@builtin/facult-operating-model/instructions/LEARNING_AND_WRITEBACK.md`.\\nFor deciding whether capability belongs in global or project scope, read `@builtin/facult-operating-model/instructions/PROJECT_CAPABILITY.md`.\\nFor project operating-layer design, read `@builtin/facult-operating-model/instructions/INTEGRATION.md`.\\n\\nBuiltin specialist agents are available for:\\n- writeback curation\\n- evolution planning\\n- scope promotion\\n- integration auditing\\n\\nBuiltin skills are available for:\\n- capability evolution\\n- project operating-layer design\\n","agents/evolution-planner/agent.toml":"name = \\"evolution-planner\\"\\ndescription = \\"Turn repeated writeback into concrete capability proposals.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou plan capability evolution.\\n\\nPrioritize:\\n- smallest useful change\\n- correct target asset type\\n- correct target scope\\n- evidence that justifies the change\\n- repeated writeback clusters or clearly missing capabilities, not isolated preferences\\n\\nProposal kinds you should consider first:\\n- update_asset\\n- create_asset\\n- extract_snippet\\n- add_skill\\n- promote_asset\\n\\nDefault to project scope when the pattern is repo-local.\\nPromote to global only when reuse is demonstrated and pollution risk is low.\\n\\nReturn concise proposals ordered by expected leverage, including:\\n- proposal kind\\n- target asset\\n- target scope\\n- why this is the smallest durable change\\n\\nDo not escalate to evolution when a single writeback is enough.\\nDo not use evolution as a substitute for executable task tracking when the main need is owner, priority, state, or implementation follow-through.\\n\\"\\"\\"\\n","agents/integration-auditor/agent.toml":"name = \\"integration-auditor\\"\\ndescription = \\"Find where local success can still fail system-wide.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou audit integration risk.\\n\\nPrioritize:\\n- hidden dependencies\\n- rollout hazards\\n- operational constraints\\n- gaps between local verification and real system behavior\\n\\nReturn concise findings ordered by impact.\\n\\"\\"\\"\\n","agents/scope-promoter/agent.toml":"name = \\"scope-promoter\\"\\ndescription = \\"Decide whether learning belongs at project or global scope.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou decide scope.\\n\\nPrioritize:\\n- project specificity\\n- cross-project reuse potential\\n- pollution risk from globalizing too early\\n\\nWhen recommending promotion, make the standard path explicit:\\n- keep the source capability in project scope until promotion is approved\\n- create a reviewable global proposal\\n- do not treat promotion as implicit apply\\n\\nReturn concise decisions with rationale.\\n\\"\\"\\"\\n","agents/writeback-curator/agent.toml":"name = \\"writeback-curator\\"\\ndescription = \\"Turn noisy outcomes into high-signal writeback.\\"\\n\\ndeveloper_instructions = \\"\\"\\"\\nYou curate durable writeback.\\n\\nPrioritize:\\n- repeated failures\\n- repeated wins\\n- stale guidance\\n- missing capability edges\\n- tool, skill, MCP, plugin, automation, or instruction friction that repeatedly slows work down\\n\\nFor each recommendation, prefer returning:\\n- suggested writeback kind\\n- best target asset or destination\\n- best scope (`project` or `global`)\\n- the evidence that justifies recording it\\n\\nDo not emit low-signal noise.\\nIf the learning is repo-specific, keep it project-scoped by default.\\nWhen the signal is already strong and the target is clear, prefer recommending direct writeback capture rather than abstract advice.\\nWhen the issue is executable tooling work, recommend task tracking for the fix and writeback only for the reusable operating-model learning.\\n\\"\\"\\"\\n","instructions/EVOLUTION.md":"---\\ndescription: Turn repeated signal into concrete capability changes.\\ntags: [facult, evolution, writeback]\\n---\\n\\n# Evolution\\n\\nUse writeback and evolution to improve the AI operating layer itself.\\n\\nEvolution is the synthesis and change side of the feedback loop. It turns accumulated writebacks, repeated tool friction, stale canonical assets, or clearly missing capability into small reviewable changes to instructions, skills, snippets, agents, or other markdown canonical assets.\\n\\n## When To Record Writeback\\n\\nRecord writeback when one of these is true:\\n\\n- the same failure repeats\\n- the same success pattern repeats\\n- guidance is stale or missing\\n- a prompt or loop has to be restated often\\n- a project-specific pattern looks reusable\\n\\nDo not record low-signal noise:\\n\\n- one-off annoyance with no reuse value\\n- generic \\"could be better\\" commentary\\n- duplicate observations with no new evidence\\n\\nThe intended default is that agents record strong writebacks themselves when the signal is clear enough, rather than only recommending that a user do it manually later.\\n\\nDo not wait for a weekly review to preserve high-signal evidence. Do wait for repeated evidence or a clearly missing capability before drafting a proposal.\\n\\n## Scope\\n\\nChoose `project` scope when the learning depends on:\\n\\n- repo architecture\\n- team workflow\\n- project tooling\\n- local testing or verification behavior\\n\\nChoose `global` scope when the learning is reusable across projects.\\n\\nPromote from project to global only after repeated reuse or strong evidence.\\n\\n## Writeback Kinds\\n\\nCommon kinds:\\n\\n- `weak_verification`\\n- `false_positive`\\n- `missing_context`\\n- `reusable_pattern`\\n- `capability_gap`\\n- `bad_default`\\n\\nEvery good writeback should try to include:\\n\\n- a concrete summary\\n- the best target asset if known\\n- the right scope\\n- domain or tags when useful\\n\\n## Operator Flow\\n\\nTypical workflow:\\n\\n```bash\\nfclt ai writeback add --kind weak_verification --summary \\"Checks were too shallow\\" --asset instruction:VERIFICATION\\nfclt ai writeback group --by asset\\nfclt ai writeback summarize --by domain\\nfclt ai evolve propose\\nfclt ai evolve draft EV-00001\\nfclt ai evolve accept EV-00001\\nfclt ai evolve apply EV-00001\\n```\\n\\nUse `fclt ai evolve draft <id> --append \\"...\\"` to revise a draft while preserving draft history.\\n\\nReview surfaces:\\n\\n- open `~/.ai/writebacks/` and `~/.ai/evolution/` in a Markdown editor for frontmatter-rich global and project-scoped review artifacts\\n- `fclt status --json` for queue/proposal paths, review artifact paths, counts, and active scope\\n- `fclt ai writeback list|show|group|summarize` for raw and clustered signal\\n- `fclt ai evolve list|show|review` for proposal state without applying changes\\n- `fclt templates init automation learning-review` for recurring capture/review\\n- `fclt templates init automation evolution-review` for recurring proposal review\\n- `fclt templates init automation tool-call-audit` for repeated tool-friction review\\n\\nEvolution proposal metadata, markdown drafts, patch artifacts, writeback queues,\\nand journals are runtime state. `fclt` stores JSON queues, proposal records,\\ndraft refs, patches, and journals in machine-local Facult state. It mirrors\\nhuman-readable review artifacts into global `~/.ai/writebacks/...` and\\n`~/.ai/evolution/...`, including project-scoped artifacts under\\n`projects/<slug-hash>/` with cwd/project metadata in frontmatter. Canonical\\nassets in `~/.ai` or `<repo>/.ai` should only change when a proposal is applied.\\n\\n## Default Agent Behavior\\n\\nUse the smallest action that fits the signal:\\n\\n1. record one strong writeback when there is a clear durable learning\\n2. use `writeback-curator` when the target, kind, or scope is ambiguous\\n3. use `capability-evolution` or `evolution-planner` when repeated signal should become a proposal\\n4. do not draft or apply proposals just because a writeback exists; require repeated evidence or a clearly missing capability\\n\\nAvoid creating writeback/evolution noise for one-off nits, vague preferences, or speculative ideas without evidence.\\n\\nWhen the friction is executable product/tooling work that needs ownership,\\npriority, state, or implementation follow-through, create or update a real task\\nsystem item instead of forcing it into capability evolution. Use evolution for\\nthe reusable operating-layer change.\\n\\n## Proposal Kinds\\n\\nCurrent supported proposal kinds:\\n\\n- `update_asset`\\n- `create_asset`\\n- `extract_snippet`\\n- `add_skill`\\n- `promote_asset`\\n\\nUse the smallest durable change that fits the evidence.\\n\\n## Review And Apply Rules\\n\\n- draft before apply\\n- accept before apply\\n- prefer the smallest safe change\\n- keep reviewable evidence tied to source writebacks\\n- do not globalize project behavior too early\\n- do not apply high-risk global instruction, skill, plugin, or shared-tool changes without explicit review/approval\\n\\nApply is for markdown canonical assets only. If the target is wrong, revise the proposal rather than forcing it through.\\n","instructions/INTEGRATION.md":"---\\ndescription: Detect where local success can still fail at integration boundaries.\\ntags: [facult, integration, verification]\\n---\\n\\n# Integration\\n\\nDistinguish local correctness from system correctness. Check hidden dependencies, rollout order, and operational constraints before calling work done.\\n","instructions/LEARNING_AND_WRITEBACK.md":"---\\ndescription: Preserve durable signal and record writeback when the operating layer should learn.\\ntags: [facult, learning, writeback]\\n---\\n\\n# Learning And Writeback\\n\\nUse this when work produces a durable decision, failure, success pattern, or missing guardrail that should outlive the current task.\\n\\nThis is the capture side of the feedback loop. The goal is to let normal agent work produce reusable signal without requiring a human to manually restate every friction point later.\\n\\n## Default Behavior\\n\\nThe normal path should be agent-driven.\\n\\nIf you can clearly answer:\\n\\n- what was learned\\n- why it matters\\n- where it should land\\n- whether it belongs in `project` or `global`\\n\\nthen record the writeback instead of only suggesting that someone should do it later.\\n\\nUse:\\n\\n```bash\\nfclt ai writeback add --kind <kind> --summary \\"<summary>\\" --asset <asset-selector>\\n```\\n\\nThe writeback queue is runtime state, not canonical source. `fclt` stores JSON\\nqueue state in machine-local Facult state so sandboxed agents can record durable\\nfriction without mutating canonical assets unless an evolution proposal is later\\nreviewed and applied.\\n\\nEvery writeback also refreshes a Markdown review artifact under the global\\n`~/.ai/writebacks/...` tree. Global signal lands in `~/.ai/writebacks/global/`;\\nproject-scoped signal lands in `~/.ai/writebacks/projects/<slug-hash>/` with\\nfrontmatter for scope, project root, cwd, target asset, status, tags, evidence,\\nand timestamps. Do not write writeback review artifacts into a repo-local `.ai`;\\nrepo-local state should contribute project metadata and evidence, not bundled\\nprivate review files.\\n\\nProject-scoped writebacks should usually be recorded from the repo that produced\\nthe evidence. Global writebacks should be reserved for shared doctrine, shared\\nskills, shared agents, tool behavior, or cross-project capability gaps.\\n\\n## Record Writeback When\\n\\n- the same failure or weak loop appears again\\n- a reusable success pattern shows up\\n- guidance is clearly stale or missing\\n- a repo-local behavior probably belongs in project capability\\n- a cross-project behavior probably belongs in global capability\\n- a skill, tool, MCP, plugin, automation, or instruction gap repeatedly slows work down\\n- an agent has to restate the same workaround, verification rule, or review rule\\n\\n## Do Not Record Writeback For\\n\\n- one-off annoyance with no durable value\\n- weak commentary with no target\\n- speculative ideas without evidence\\n- duplicate noise with no new signal\\n\\n## Follow Through\\n\\n- prefer one strong writeback over many weak ones\\n- mention the writeback id when summarizing what changed\\n- escalate to `capability-evolution` or `fclt ai evolve ...` only when the signal is repeated or clearly points at a durable capability change\\n- use `fclt ai writeback group --by asset` or `fclt ai writeback summarize --by domain` to review accumulated signal before proposing broad changes\\n- use scheduled `learning-review`, `evolution-review`, or `tool-call-audit` automations when the signal should be reviewed in the background\\n","instructions/PROJECT_CAPABILITY.md":"---\\ndescription: Decide what belongs in repo-local .ai versus the global store.\\ntags: [facult, project, scope]\\n---\\n\\n# Project Capability\\n\\nPrefer project scope when the guidance depends on repo architecture, team workflow, or colocated tooling. Promote to global only after repeated cross-project reuse.\\n\\n## Project First\\n\\nDefault to `<repo>/.ai` when the capability is about:\\n\\n- local architecture\\n- repo-specific testing or verification\\n- team conventions\\n- project tools and workflows\\n\\n## Promote Carefully\\n\\nPromote to `~/.ai` only when:\\n\\n- the same pattern succeeds in more than one repo\\n- the capability is not coupled to local architecture\\n- the global version will not create noise for unrelated projects\\n\\nUse:\\n\\n```bash\\nfclt ai evolve promote EV-00001 --to global --project\\n```\\n\\nThat creates a new global proposal for review. It does not auto-apply the promotion.\\n","instructions/WORK_UNITS.md":"---\\ndescription: \\"Define work units so agent tasks have a clear goal, evidence path, artifact, and writeback target.\\"\\ntags: [\\"work-units\\", \\"planning\\", \\"verification\\", \\"writeback\\"]\\n---\\n\\n# Work Units\\n\\nA work unit is the smallest coherent unit of agent work that can be understood, verified, and preserved.\\n\\nIt is not just the user\'s latest sentence. It is the operational shape around that sentence: what is being changed, why it matters, what evidence is needed, what artifact should remain, and how future agents should benefit from the result.\\n\\n## Minimum Contract\\n\\nA well-formed work unit names:\\n\\n- goal: the outcome the user needs\\n- acceptance criteria: what must be true when the work is done\\n- required context: source files, docs, systems, messages, or prior decisions needed for correctness\\n- constraints: permissions, privacy, compatibility, deadlines, ownership, or scope limits\\n- signals or evidence: checks that can confirm progress or falsify assumptions\\n- output artifact: code, docs, proposal, issue, note, draft, or report\\n- verification path: commands, review surfaces, manual checks, or source-of-truth reads\\n- writeback target: where durable learning belongs if the work teaches something reusable\\n\\nIf one of these is missing and the gap blocks correctness, surface the gap early and recover it before moving faster.\\n\\n## Why It Exists\\n\\nWork-unit framing prevents shallow completion. It helps agents avoid:\\n\\n- changing files before understanding the target\\n- treating a weak green signal as proof\\n- losing reusable learning in chat\\n- creating duplicate tasks or proposals\\n- turning one-off preferences into global rules\\n- pushing project-specific details into global capability\\n\\n## How To Use It\\n\\nFor simple tasks, keep the work unit implicit but still verify the result.\\n\\nFor ambiguous, high-impact, or multi-step tasks, make the work unit explicit before executing. A compact form is enough:\\n\\n```text\\nGoal:\\nAcceptance:\\nContext:\\nConstraints:\\nEvidence:\\nArtifact:\\nVerification:\\nWriteback:\\n```\\n\\nUse the smallest framing that makes the task correct. Do not turn every request into paperwork.\\n\\n## Writeback\\n\\nWhen the work reveals durable friction, missing capability, stale guidance, or a repeatable workflow, prefer one strong writeback over many weak ones.\\n\\nUse `fclt ai writeback add ...` when the target asset, scope, and evidence are clear. Use `fclt ai evolve ...` only when repeated signal supports a concrete proposal.\\n","skills/capability-evolution/SKILL.md":"---\\ndescription: Convert repeated writeback into concrete fclt capability proposals.\\ntags: [facult, evolution, writeback]\\n---\\n\\n# capability-evolution\\n\\n## When To Use\\nUse this skill when the same missing guidance, weak loop, or recurring win appears often enough that the AI system itself should probably change.\\n\\nDo not wait for a human operator by default if the signal is already clear and the environment permits local AI runtime state to be updated.\\n\\nUse writeback first when the signal is useful but not yet repeated. Use evolution when accumulated writebacks, repeated tool friction, or a clearly missing capability point at a specific target asset or new capability.\\n\\n## Scope Decision\\n\\nChoose `project` when the behavior depends on repo-local architecture or workflow.\\n\\nChoose `global` when the behavior is broadly reusable.\\n\\nIf unsure, start at project scope and promote later with evidence.\\n\\n## Working Flow\\n\\n1. record the strongest writeback\\n2. group or summarize repeated signal\\n3. choose the smallest valid proposal kind\\n4. draft the proposal\\n5. accept only after the target and scope are correct\\n6. apply only when the markdown target is the intended canonical asset\\n\\nUse:\\n\\n```bash\\nfclt ai writeback add ...\\nfclt ai writeback group --by asset\\nfclt ai writeback summarize --by domain\\nfclt ai evolve propose\\nfclt ai evolve draft EV-00001\\nfclt ai evolve draft EV-00001 --append \\"tighten the rule with a concrete verification step\\"\\nfclt ai evolve accept EV-00001\\nfclt ai evolve apply EV-00001\\n```\\n\\nFor background review loops, use:\\n\\n```bash\\nfclt templates init automation learning-review\\nfclt templates init automation evolution-review\\nfclt templates init automation tool-call-audit\\n```\\n\\nIf there is not yet enough repeated signal for evolution, record the writeback and stop there.\\n\\n## Proposal Kind Selection\\n\\n- `update_asset` for tightening existing guidance\\n- `create_asset` for missing instructions or docs\\n- `extract_snippet` for reusable partial guidance\\n- `add_skill` for reusable workflow instruction\\n- `promote_asset` for project-to-global promotion\\n\\nUse task tracking instead of evolution when the main work is an executable tool or product fix that needs an owner, priority, state, or delivery plan. Use evolution for the reusable instruction, skill, or operating-model change that should survive that fix.\\n\\n## Output Contract\\n- repeated signal\\n- proposed asset change\\n- target scope\\n- evidence\\n- smallest useful next step\\n","skills/project-operating-layer-design/SKILL.md":"---\\ndescription: Design or improve a repo-local .ai operating layer.\\ntags: [facult, project, design]\\n---\\n\\n# project-operating-layer-design\\n\\n## When To Use\\nUse this skill when a project needs its own `.ai/` structure, repo-specific instructions, or local bootstrap guidance.\\n\\n## Output Contract\\n- recommended `.ai/` layout\\n- what stays project-local\\n- what stays global\\n- what should remain generated runtime output only\\n"}'
 ) as Record<string, string>;

package/src/remote.ts

@@ -9,8 +9,9 @@ import {
   relative,
   resolve,
 } from "node:path";
-import { fileURLToPath } from "node:url";
 import { isCancel, multiselect, select, text } from "@clack/prompts";
+import { facultBuiltinPackRoot } from "./builtin";
+import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
 import {
   renderBullets,
   renderCatalog,
@@ -1221,11 +1222,6 @@ updated_at = ${timestamp}
   };
 }
 
-function builtinPackRoot(packName: string): string {
-  const here = dirname(fileURLToPath(import.meta.url));
-  return join(here, "..", "assets", "packs", packName);
-}
-
 async function pathExists(pathValue: string): Promise<boolean> {
   try {
     await Bun.file(pathValue).stat();
@@ -1258,15 +1254,15 @@ async function listFilesRecursive(rootDir: string): Promise<string[]> {
   return out.sort();
 }
 
-async function scaffoldBuiltinProjectAiPack(args: {
-  cwd?: string;
+async function scaffoldBuiltinOperatingModelPack(args: {
+  rootDir: string;
   homeDir?: string;
   dryRun?: boolean;
   force?: boolean;
+  installedAs?: string;
 }): Promise<InstallResult> {
-  const cwd = resolve(args.cwd ?? process.cwd());
-  const rootDir = join(cwd, ".ai");
-  const packRoot = builtinPackRoot("facult-operating-model");
+  const rootDir = resolve(args.rootDir);
+  const packRoot = facultBuiltinPackRoot("facult-operating-model");
   const files = await listFilesRecursive(packRoot);
   const changedPaths: string[] = [];
 
@@ -1307,7 +1303,7 @@ async function scaffoldBuiltinProjectAiPack(args: {
   return {
     ref: `${BUILTIN_INDEX_NAME}:facult-operating-model`,
     type: "skill",
-    installedAs: "project-ai",
+    installedAs: args.installedAs ?? "operating-model",
     path: rootDir,
     sourceTrustLevel: "trusted",
     dryRun: Boolean(args.dryRun),
@@ -1315,6 +1311,22 @@ async function scaffoldBuiltinProjectAiPack(args: {
   };
 }
 
+async function scaffoldBuiltinProjectAiPack(args: {
+  cwd?: string;
+  homeDir?: string;
+  dryRun?: boolean;
+  force?: boolean;
+}): Promise<InstallResult> {
+  const cwd = resolve(args.cwd ?? process.cwd());
+  return await scaffoldBuiltinOperatingModelPack({
+    rootDir: join(cwd, ".ai"),
+    homeDir: args.homeDir,
+    dryRun: args.dryRun,
+    force: args.force,
+    installedAs: "project-ai",
+  });
+}
+
 function compareVersions(a: string, b: string): number {
   const aTokens = (a.match(VERSION_TOKEN_RE) ?? []).map((t) => t.toLowerCase());
   const bTokens = (b.match(VERSION_TOKEN_RE) ?? []).map((t) => t.toLowerCase());
@@ -2658,6 +2670,9 @@ function printTemplatesHelp() {
               "fclt templates init snippet <marker> [--force] [--dry-run]"
             ),
             renderCode("fclt templates init agents [--force] [--dry-run]"),
+            renderCode(
+              "fclt templates init operating-model [--global|--project|--root PATH] [--force] [--dry-run]"
+            ),
             renderCode("fclt templates init project-ai [--force] [--dry-run]"),
             renderCode(
               "fclt templates init automation <template-id> [--scope global|project|wide] [--name <name>] [--project-root <path>] [--cwds <path1,path2>] [--rrule <RRULE>] [--status PAUSED|ACTIVE] [--yes] [--dry-run]"
@@ -3052,6 +3067,14 @@ export async function templatesCommand(
         description: item.description ?? "",
         version: item.version ?? "",
       })),
+      {
+        id: "operating-model",
+        type: "pack",
+        title: "Operating Model Pack",
+        description:
+          "Install the built-in Facult operating-model pack into the active canonical root.",
+        version: "1.0.0",
+      },
       {
         id: "project-ai",
         type: "pack",
@@ -3101,7 +3124,7 @@ export async function templatesCommand(
   const [kind, ...args] = rest;
   if (!kind) {
     console.error(
-      "templates init requires a kind (skill|mcp|agent|snippet|agents|claude|project-ai|automation)"
+      "templates init requires a kind (skill|mcp|agent|snippet|agents|claude|operating-model|project-ai|automation)"
     );
     process.exitCode = 2;
     return;
@@ -3144,6 +3167,51 @@ export async function templatesCommand(
     }
   }
 
+  if (kind === "operating-model") {
+    try {
+      const context = parseCliContextArgs(args, { allowScope: false });
+      const cwd = resolve(ctx.cwd ?? process.cwd());
+      const rootDir = ctx.rootDir
+        ? resolve(ctx.rootDir)
+        : context.scope === "project" && !context.rootArg
+          ? join(findGitRootFromPath(cwd) ?? cwd, ".ai")
+          : resolveCliContextRoot({
+              rootArg: context.rootArg,
+              scope: context.scope,
+              homeDir: ctx.homeDir,
+              cwd,
+            });
+      const result = await scaffoldBuiltinOperatingModelPack({
+        rootDir,
+        homeDir: ctx.homeDir,
+        dryRun,
+        force,
+      });
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      const action = dryRun ? "Would install" : "Installed";
+      console.log(
+        renderPage({
+          title: `fclt templates init ${kind}`,
+          subtitle: `${action} ${result.installedAs} into ${result.path}`,
+          sections: [
+            {
+              title: "Changed Paths",
+              lines: renderBullets(result.changedPaths),
+            },
+          ],
+        })
+      );
+      return;
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   let ref = "";
   let as: string | undefined;
   if (kind === "skill") {