facult 2.10.0 → 2.12.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,28 @@ 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
+- [Composable Capability](./docs/composable-capability.md): refs, snippets, instruction templates, and evolvable units
+- [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, capability composition, 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
@@ -222,6 +240,8 @@ The intended feedback loop is:
 4. only repeated evidence, a clearly missing capability, or a stale canonical asset becomes an evolution proposal
 5. accepted proposals update canonical markdown assets, skills, snippets, or project/global instructions
 
+Composition matters: prefer atomic instructions such as `BUN.md` or `RUST.md`, snippets for repeated rendered blocks, skills for workflows, agents for delegated roles, MCP/tool config for tool interfaces, and automations for scheduled loops. Record writeback against the smallest unit that needs to improve.
+
 If you want to disable default built-in sync for one canonical root:
 
 ```toml
@@ -238,14 +258,17 @@ 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
 fclt templates init agents
 fclt templates init agent review-operator
+fclt templates init instruction BUN
+fclt templates init snippet global/lang/bun
 fclt templates init skill facult-manager
 
 # Enable that skill for managed tools
@@ -269,7 +292,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:
 
@@ -412,6 +435,33 @@ fclt snippets sync [--dry-run] [file...]
 
 Snippets are already used during global Codex `AGENTS.md` rendering.
 
+### Composable instructions and refs
+
+Use instruction templates for atomic reusable doctrine:
+
+```bash
+fclt templates init instruction BUN
+fclt templates init instruction lang/RUST
+fclt show instruction:BUN
+```
+
+Use canonical refs to compose instructions without hard-coding paths:
+
+```text
+@ai/instructions/BUN.md
+@project/instructions/TESTING.md
+@builtin/facult-operating-model/instructions/WORK_UNITS.md
+```
+
+Use snippets when a repeated block should be inserted into rendered docs and evolved independently:
+
+```md
+<!-- fclty:global/lang/bun -->
+<!-- /fclty:global/lang/bun -->
+```
+
+The composition rule is simple: instructions hold doctrine, snippets hold repeated blocks, skills hold workflows, agents hold roles, MCP/tool config holds interfaces, and automations hold scheduled review loops. Writeback and evolution should target the smallest unit that actually needs to change.
+
 ### Graph inspection
 
 The generated graph in `.ai/.facult/ai/graph.json` is queryable directly:
@@ -622,10 +672,12 @@ 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>
 fclt templates init agent <name>
+fclt templates init instruction <name>
 fclt templates init snippet <marker>
 fclt templates init agents
 fclt templates init automation <template-id> --scope global|project|wide [--name <name>] [--project-root <path>] [--cwds <path1,path2>] [--rrule <RRULE>] [--status PAUSED|ACTIVE]
@@ -849,7 +901,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,8 @@ 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 composing refs, snippets, instructions, skills, agents, MCP, and automations as evolvable units, read `@builtin/facult-operating-model/instructions/CAPABILITY_COMPOSITION.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/CAPABILITY_COMPOSITION.md

@@ -0,0 +1,76 @@
+---
+description: "Compose small capability units across global and project roots, then evolve the smallest affected unit."
+tags: ["facult", "composition", "refs", "snippets", "instructions"]
+---
+
+# Capability Composition
+
+Use `fclt` capability as small units that can be composed, inspected, rendered, and evolved independently.
+
+The main units are:
+
+- instructions: standalone markdown doctrine such as language preferences, verification rules, or review standards
+- snippets: small markdown partials inserted into one or more rendered docs
+- skills: task-specific workflows with `SKILL.md`
+- agents: focused role manifests
+- MCP definitions: tool interfaces and their safe auth shape
+- automations: scheduled review or maintenance loops
+- tool rules/config: tool-specific defaults and policy
+
+## Composition Rules
+
+- Keep reusable doctrine in `instructions/`.
+- Keep repeated paragraphs or policy blocks in `snippets/`.
+- Keep workflow execution in `skills/`.
+- Keep persona or delegation behavior in `agents/`.
+- Keep tool wiring in `mcp/` and `tools/<tool>/`.
+- Compose broad agent docs from refs and snippets instead of copying text by hand.
+- Prefer one narrow reusable unit over one large instruction file that mixes unrelated domains.
+
+Examples:
+
+- `@ai/instructions/BUN.md` for shared Bun preferences.
+- `@ai/instructions/RUST.md` for shared Rust preferences.
+- `@project/instructions/TESTING.md` for repo-specific test policy.
+- `<!-- fclty:global/codex/baseline -->` for a shared rendered block.
+
+## Scope
+
+Use global scope for capability that should follow the user across projects.
+
+Use project scope for capability that belongs to a repo, team workflow, architecture, or local test harness.
+
+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
+
+Target the smallest affected unit.
+
+- If a paragraph is reused in several rendered docs, target the snippet.
+- If a domain rule is wrong, target the instruction.
+- If a workflow is incomplete, target the skill.
+- If a delegated role is unclear, target the agent.
+- If a tool interface is missing or unsafe, target the MCP or tool config.
+- If a scheduled review loop is noisy or missing context, target the automation.
+
+Good writeback targets are graph-backed selectors when possible:
+
+```bash
+fclt ai writeback add --kind missing_context --summary "Bun guidance did not cover test runner selection." --asset instruction:BUN
+fclt ai writeback add --kind reusable_pattern --summary "Project test policy should become a shared verification snippet." --asset @project/instructions/TESTING.md
+fclt ai writeback add --kind bad_default --summary "The review automation escalated one-off preferences." --asset automation:evolution-review
+```
+
+Use `fclt ai evolve ...` only after repeated signal, a clearly missing capability, or a stale canonical asset points at a concrete change. Prefer the smallest valid proposal kind: `update_asset`, `create_asset`, `extract_snippet`, `add_skill`, or `promote_asset`.
+
+## Agent Defaults
+
+When an agent sees a repeated preference like "use Bun for JS projects" or "prefer Cargo nextest for Rust tests", it should not bury that in chat. It should identify whether the durable unit is:
+
+- a global instruction
+- a project instruction
+- a snippet reused by rendered docs
+- a skill workflow
+- a project-to-global promotion candidate
+
+Then it should record writeback against that unit, or draft a proposal when the evidence is already strong enough.

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

@@ -9,6 +9,8 @@ Use writeback and evolution to improve the AI operating layer itself.
 
 Evolution 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.
 
+Use capability composition when choosing the target. Instructions, snippets, skills, agents, MCP/tool config, and automations are separate units. Target the smallest unit that actually needs to change instead of rewriting a broad agent doc.
+
 ## When To Record Writeback
 
 Record writeback when one of these is true:
@@ -60,6 +62,14 @@ Every good writeback should try to include:
 - the right scope
 - domain or tags when useful
 
+Good target examples:
+
+- `instruction:BUN` when shared Bun guidance is stale or missing
+- `@project/instructions/TESTING.md` when repo test policy needs project-scoped evolution
+- `snippet:global/lang/bun` when a repeated rendered block should be fixed or extracted
+- `skill:capability-evolution` when a workflow skill is missing steps or examples
+- `automation:evolution-review` when the scheduled review loop is noisy or incomplete
+
 ## Operator Flow
 
 Typical workflow:
@@ -122,6 +132,14 @@ Current supported proposal kinds:
 
 Use the smallest durable change that fits the evidence.
 
+Examples:
+
+- `update_asset`: fix a stale instruction, snippet, agent, or automation markdown asset.
+- `create_asset`: add a missing instruction such as `BUN.md` or `RUST.md`.
+- `extract_snippet`: move repeated guidance out of several docs into one snippet.
+- `add_skill`: create a workflow when instructions are not enough.
+- `promote_asset`: move a proven project instruction/snippet/skill toward global reuse.
+
 ## Review And Apply Rules
 
 - draft before apply
@@ -129,6 +147,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/LEARNING_AND_WRITEBACK.md

@@ -45,6 +45,15 @@ Project-scoped writebacks should usually be recorded from the repo that produced
 the evidence. Global writebacks should be reserved for shared doctrine, shared
 skills, shared agents, tool behavior, or cross-project capability gaps.
 
+Target the smallest composable unit that explains the friction:
+
+- instruction: domain guidance, preferences, verification rules, or review doctrine
+- snippet: repeated markdown block used by more than one rendered doc
+- skill: workflow execution steps or examples
+- agent: delegated role behavior
+- MCP/tool config: tool interface, auth shape, or rendered integration
+- automation: scheduled review loop, cadence, prompt, or memory
+
 ## Record Writeback When
 
 - the same failure or weak loop appears again
@@ -54,6 +63,7 @@ skills, shared agents, tool behavior, or cross-project capability gaps.
 - a cross-project behavior probably belongs in global capability
 - a skill, tool, MCP, plugin, automation, or instruction gap repeatedly slows work down
 - an agent has to restate the same workaround, verification rule, or review rule
+- a repeated preference should become an atomic instruction such as `BUN.md`, `RUST.md`, or a project-specific testing policy
 
 ## Do Not Record Writeback For
 

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,19 @@
+# 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.
+- [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.
+
+## 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,93 @@
+# 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`
+- `CAPABILITY_COMPOSITION.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
+- composable refs, snippets, instructions, skills, agents, MCP, and automations
+- 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/composable-capability.md

@@ -0,0 +1,170 @@
+# Composable Capability
+
+`fclt` treats AI behavior as small capability units that can be composed into larger agent instructions and evolved independently.
+
+This is the core model:
+
+- write domain guidance once
+- compose it with refs and snippets
+- render it only where a tool should receive it
+- target writeback at the smallest unit that needs to change
+
+## Units
+
+Use `instructions/` for reusable markdown doctrine.
+
+Examples:
+
+```text
+~/.ai/instructions/BUN.md
+~/.ai/instructions/RUST.md
+<repo>/.ai/instructions/TESTING.md
+```
+
+Use `snippets/` for partial blocks inserted into rendered docs.
+
+Examples:
+
+```text
+~/.ai/snippets/global/codex/baseline.md
+~/.ai/snippets/global/lang/bun.md
+<repo>/.ai/snippets/global/project/testing.md
+```
+
+Use `skills/` for executable workflows, `agents/` for delegated roles, `mcp/` for tool interfaces, and `automations/` for scheduled loops.
+
+## Refs
+
+Canonical refs let a markdown asset point at another asset without hard-coding machine paths:
+
+```text
+@ai/instructions/BUN.md
+@project/instructions/TESTING.md
+@builtin/facult-operating-model/instructions/WORK_UNITS.md
+```
+
+Use global refs for reusable user-owned capability. Use project refs for repo-owned capability. Use built-in refs for packaged defaults.
+
+Config-backed refs are useful when the concrete path should be named in `config.toml`:
+
+```toml
+version = 1
+
+[refs]
+language_defaults = "@ai/instructions/BUN.md"
+project_testing = "@project/instructions/TESTING.md"
+```
+
+Rendered markdown can use those refs through the render context when a tool adapter supports that target.
+
+## Snippets
+
+Snippets use paired HTML markers:
+
+```md
+<!-- fclty:global/lang/bun -->
+<!-- /fclty:global/lang/bun -->
+```
+
+The marker above resolves to:
+
+```text
+snippets/global/lang/bun.md
+```
+
+Create and inspect snippets with:
+
+```bash
+fclt templates init snippet global/lang/bun
+fclt snippets list
+fclt snippets show global/lang/bun
+fclt snippets sync --dry-run AGENTS.global.md
+```
+
+Use snippets when the same block appears in more than one rendered doc, or when a stable block should be independently targetable by writeback and evolution.
+
+## Instruction Templates
+
+Create a new instruction scaffold with:
+
+```bash
+fclt templates init instruction BUN
+fclt templates init instruction lang/RUST
+```
+
+That writes:
+
+```text
+instructions/BUN.md
+instructions/lang/RUST.md
+```
+
+An instruction can include refs, snippet markers, examples, and writeback targeting guidance. Keep one instruction focused on one reusable domain. For example:
+
+- `BUN.md`: JavaScript runtime/package/test preferences.
+- `RUST.md`: Rust formatting, linting, and test preferences.
+- `WRITING.md`: voice and editorial rules.
+- `VERIFICATION.md`: proof standards.
+
+## Composition Pattern
+
+A global `AGENTS.global.md` can stay short and compose units:
+
+```md
+# Global Agent Instructions
+
+For work-unit framing, read `@ai/instructions/WORK_UNITS.md`.
+For JS/Bun projects, read `@ai/instructions/BUN.md`.
+For Rust projects, read `@ai/instructions/RUST.md`.
+
+<!-- fclty:global/codex/baseline -->
+<!-- /fclty:global/codex/baseline -->
+```
+
+A project can add narrower guidance:
+
+```md
+# Project Agent Instructions
+
+For project test policy, read `@project/instructions/TESTING.md`.
+For local deployment rules, read `@project/instructions/DEPLOYMENT.md`.
+```
+
+This keeps global defaults reusable and lets projects override or extend them without rewriting the whole global file.
+
+## Evolution
+
+Target the smallest unit that actually needs to change:
+
+- bad or stale domain guidance: update the instruction
+- repeated block copied in several docs: extract a snippet
+- missing workflow: add or update a skill
+- unclear delegation behavior: update an agent
+- tool integration gap: update MCP/tool config or create a tooling task
+- project-local pattern that proved reusable: promote the asset
+
+Examples:
+
+```bash
+fclt ai writeback add --kind missing_context --summary "Bun guidance did not cover test runner selection." --asset instruction:BUN
+fclt ai writeback add --kind reusable_pattern --summary "Project testing policy should become a shared verification snippet." --asset @project/instructions/TESTING.md
+fclt ai evolve propose
+```
+
+Do not create a global proposal for one-off taste. Use writeback to preserve evidence, then evolve when the signal repeats or the missing capability is already clear.
+
+## Review
+
+Use these surfaces:
+
+```bash
+fclt list instructions --global
+fclt list snippets --global
+fclt show instruction:BUN
+fclt graph deps AGENTS.global.md
+fclt graph dependents @ai/instructions/BUN.md
+fclt ai writeback group --by asset
+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.