facult 2.13.9 → 2.15.0

package/README.md

@@ -15,10 +15,6 @@
   </a>
 </div>
 
-<p align="center">
-  <img alt="fclt demo" src="./Ghostty.gif">
-</p>
-
 `fclt` is a CLI for managing AI capability across tools and projects.
 
 It gives instructions, snippets, skills, agents, MCP definitions, automations, and tool config a shared home. It can inspect what already exists, consolidate duplicates, render selected capability into tools like Codex and Claude, and preserve real-work friction as writeback that can later become reviewed improvements.
@@ -31,6 +27,8 @@ Use it when AI setup has become scattered across dotfiles, tool homes, repos, pr
 
 Most usage should be agent-led after setup. Humans install, inspect, audit, and approve broad changes. Agents use `fclt` to find the right capability, preserve friction as writeback, and turn repeated signal into reviewed improvements.
 
+The basic operating unit is the work unit: a piece of agent work with a goal, context, constraints, evidence, an output artifact, verification, and a writeback target when the work teaches something reusable. That frame applies to normal coding, research, docs, setup, operations, and debugging work, not only to skill updates.
+
 ## What it does
 
 `fclt` helps you:
@@ -39,6 +37,7 @@ Most usage should be agent-led after setup. Humans install, inspect, audit, and
 - keep repo-specific capability in `<repo>/.ai`
 - inspect skills, instructions, MCP servers, agents, automations, and rendered outputs
 - compose guidance from smaller units with refs and snippets
+- give agents a reusable work-unit frame for normal work
 - optionally render approved capability into Codex, Claude, Cursor, and similar tools
 - record writebacks when an agent finds missing context, weak verification, stale guidance, or tool friction
 - turn repeated writeback into reviewable evolution proposals
@@ -140,6 +139,15 @@ fclt templates init operating-model --global
 fclt index --global
 ```
 
+On first install, `fclt` seeds `AGENTS.global.md` from existing global agent docs such as `~/.codex/AGENTS.md` or `~/.claude/CLAUDE.md` when they exist, then appends the Facult operating-model frame. The packaged template is only the fallback.
+
+Refresh an existing operating-model pack without overwriting local edits:
+
+```bash
+fclt templates init operating-model --global --update --dry-run
+fclt templates init operating-model --global --update
+```
+
 Create a repo-local `.ai` root:
 
 ```bash
@@ -209,7 +217,7 @@ Canonical capability can include:
 - `mcp/`: MCP server definitions and overlays
 - `automations/`: scheduled review loops
 - `tools/<tool>/`: tool config and rules
-- `AGENTS.global.md`: composed agent guidance
+- `snippets/templates/agents-global.md`: source template materialized as `AGENTS.global.md`
 
 Refs let markdown point at canonical assets without hard-coding paths:
 
@@ -228,6 +236,8 @@ Snippet markers let repeated blocks stay independently editable:
 
 The rule is simple: target the smallest unit that needs to change. Use instructions for doctrine, snippets for repeated blocks, skills for workflows, agents for roles, MCP/tool config for interfaces, and automations for scheduled loops.
 
+Work units give those assets a practical operating frame. They keep intent, evidence, verification, output, and learning attached to a task so repeated friction can become writeback and evolution instead of disappearing into chat history.
+
 ## Writeback and evolution
 
 Writeback is preserved signal from real work. Evolution turns repeated signal into reviewed changes.
@@ -278,6 +288,7 @@ Install it without managing any tool:
 fclt templates init operating-model --global
 fclt templates init operating-model --project
 fclt templates init operating-model --root /path/to/.ai
+fclt templates init operating-model --global --update
 ```
 
 The pack is also available as built-in refs under:
@@ -352,8 +363,8 @@ Canonical store:
 
 ```bash
 fclt templates list
-fclt templates init operating-model [--global|--project|--root PATH]
-fclt templates init project-ai
+fclt templates init operating-model [--global|--project|--root PATH] [--update]
+fclt templates init project-ai [--update]
 fclt templates init instruction <name>
 fclt templates init snippet <marker>
 fclt templates init skill <name>
@@ -400,9 +411,12 @@ Use `fclt --help` and `fclt <command> --help` for exact flags.
 Start with:
 
 - [Concepts](./docs/concepts.md): roots, scopes, state layers, and asset types
+- [Work Units](./docs/work-units.md): general-purpose agent work framing
 - [Composable Capability](./docs/composable-capability.md): refs, snippets, instruction templates, and evolvable units
 - [Project `.ai`](./docs/project-ai.md): repo-owned capability and project sync policy
 - [Built-in pack](./docs/built-in-pack.md): packaged work-unit, writeback, and evolution defaults
+- [Built-in pack upgrades](./docs/pack-upgrades.md): non-destructive refresh behavior for existing `.ai` roots
+- [Codex plugin](./docs/codex-plugin.md): installable Codex skills and MCP tools for fclt workflows
 - [Writeback and evolution](./docs/writeback-evolution.md): the feedback-loop workflow and review surfaces
 - [Managed mode](./docs/managed-mode.md): when to let `fclt` write tool files
 - [Roadmap](./docs/roadmap.md): current gaps and planned work
@@ -411,7 +425,7 @@ Start with:
 
 ### Does fclt run an MCP server?
 
-Not yet as a first-party runtime. Today, `fclt` is CLI-first. You can scaffold MCP definitions that delegate to the CLI, and a dedicated plugin/MCP surface is on the roadmap.
+The core product is still CLI-first. The first-party Codex plugin includes a small stdio MCP wrapper that delegates to the installed `fclt` binary for status, doctor, paths, setup, writeback, and evolution workflows. See [Codex plugin](./docs/codex-plugin.md).
 
 ### Does fclt have to manage Codex or Claude files?
 
@@ -428,3 +442,7 @@ Commit canonical project assets that belong to the repo: instructions, snippets,
 ## Contributing
 
 Contributor and release workflow details live in [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Background
+
+The operating model behind `fclt` is related to the argument in [Governing the Machine](https://www.hack.dance/writing/governing-the-machine): as machine execution gets cheaper, the hard problem becomes governing work, evidence, memory, integration, and improvement.

package/assets/packs/facult-operating-model/agents/evolution-planner/agent.toml

@@ -26,7 +26,10 @@ Return concise proposals ordered by expected leverage, including:
 - target asset
 - target scope
 - why this is the smallest durable change
+- source writeback ids or evidence summary
+- approval risk and verification path
 
 Do not escalate to evolution when a single writeback is enough.
 Do not use evolution as a substitute for executable task tracking when the main need is owner, priority, state, or implementation follow-through.
+Do not globalize private, repo-specific, or speculative guidance.
 """

package/assets/packs/facult-operating-model/agents/integration-auditor/agent.toml

@@ -9,6 +9,13 @@ Prioritize:
 - rollout hazards
 - operational constraints
 - gaps between local verification and real system behavior
+- packaged, installed, rendered, or synced paths that differ from source behavior
+- parallel execution and state-location risks
+- privacy boundaries between global, project, generated, and machine-local state
 
-Return concise findings ordered by impact.
+Return concise findings ordered by impact. For each finding include:
+- boundary at risk
+- why the current evidence is or is not enough
+- strongest next verification step
+- whether the fix belongs in code, docs, a task, or capability evolution
 """

package/assets/packs/facult-operating-model/agents/scope-promoter/agent.toml

@@ -8,11 +8,18 @@ Prioritize:
 - project specificity
 - cross-project reuse potential
 - pollution risk from globalizing too early
+- private or repo-specific details that must not move into global capability
+- whether a smaller snippet, instruction, skill, or agent should be promoted instead of a broad doc
 
 When recommending promotion, make the standard path explicit:
 - keep the source capability in project scope until promotion is approved
 - create a reviewable global proposal
 - do not treat promotion as implicit apply
 
-Return concise decisions with rationale.
+Return concise decisions with:
+- recommended scope
+- target asset or smallest unit
+- evidence for reuse
+- privacy/pollution risk
+- promotion path or no-op rationale
 """

package/assets/packs/facult-operating-model/agents/writeback-curator/agent.toml

@@ -16,9 +16,11 @@ For each recommendation, prefer returning:
 - best target asset or destination
 - best scope (`project` or `global`)
 - the evidence that justifies recording it
+- whether the signal is enough for writeback only, task tracking, or evolution
 
 Do not emit low-signal noise.
 If the learning is repo-specific, keep it project-scoped by default.
 When the signal is already strong and the target is clear, prefer recommending direct writeback capture rather than abstract advice.
 When the issue is executable tooling work, recommend task tracking for the fix and writeback only for the reusable operating-model learning.
+When the issue contains private project details, preserve the general learning without copying private details into a global asset.
 """

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

@@ -6,3 +6,47 @@ tags: [facult, integration, verification]
 # Integration
 
 Distinguish local correctness from system correctness. Check hidden dependencies, rollout order, and operational constraints before calling work done.
+
+## When To Use
+
+Use this when a local green signal may still fail at a boundary:
+
+- code passes focused tests but has not been checked against the real workflow
+- docs are correct in isolation but may send agents to a stale command or path
+- a tool command works locally but may fail under packaged, sandboxed, or parallel execution
+- a capability change renders into one agent tool but not another
+- a project-local improvement may collide with global defaults or managed output
+- a migration, release, or rollout has ordering constraints
+
+## Integration Questions
+
+Ask the smallest set that matches the risk:
+
+- What consumes this output?
+- What state does this depend on?
+- What happens if two agents or commands run this at the same time?
+- Does the packaged/released path behave like the source checkout?
+- Does the project-scoped path avoid leaking into global or public surfaces?
+- Does the global path avoid overwriting tool-native or user-edited state?
+- Is rollback or recovery clear if the integration fails?
+
+## Evidence
+
+Prefer evidence that crosses the boundary that could fail:
+
+- run the installed CLI, packaged binary, or generated artifact when source tests are not enough
+- inspect rendered output when changing snippets, refs, or agent docs
+- use temp roots and clean homes for setup, upgrade, and sync behavior
+- verify review artifacts land in global `~/.ai/writebacks` or `~/.ai/evolution`, not repo-local private state
+- check release, package, or plugin surfaces when the change affects users outside the repo
+
+## Output
+
+Return concise findings ordered by risk:
+
+- boundary checked
+- evidence used
+- remaining assumption
+- fix or follow-up if local correctness does not prove system correctness
+
+Record writeback when the same integration boundary repeatedly fails, the verification loop is too weak, or a missing skill/tool would make the boundary easier to check next time.

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

@@ -15,6 +15,28 @@ Default to `<repo>/.ai` when the capability is about:
 - repo-specific testing or verification
 - team conventions
 - project tools and workflows
+- product, customer, deployment, or operational context tied to one repo
+- examples that would leak private or irrelevant detail if copied globally
+
+Project capability should travel with the repo when it is safe to commit. Generated state, machine-local runtime state, secrets, and review queues should not travel with it.
+
+## Global Scope
+
+Use `~/.ai` when the capability should follow the user across projects:
+
+- general verification standards
+- reusable work-unit, feedback-loop, or writeback doctrine
+- user-owned language/tool preferences that are safe to share across repos
+- cross-project skills or agents
+- MCP/tool integration patterns that are not tied to one repo
+
+Global capability should be broadly useful and low-noise. A global rule that only helps one project is usually a project rule.
+
+## Review Artifacts
+
+Project-scoped writebacks and evolution proposals use the project as evidence, but their Markdown review artifacts are mirrored under global `~/.ai/writebacks/projects/<slug-hash>/` and `~/.ai/evolution/projects/<slug-hash>/`.
+
+Do not create repo-local `writebacks/` or `evolution/` review trees inside `<repo>/.ai`. Keep private review state out of the repo while preserving project metadata in the global review artifact frontmatter.
 
 ## Promote Carefully
 
@@ -23,6 +45,8 @@ Promote to `~/.ai` only when:
 - the same pattern succeeds in more than one repo
 - the capability is not coupled to local architecture
 - the global version will not create noise for unrelated projects
+- private examples can be removed or generalized without losing the rule
+- the target global unit is smaller than a broad rewrite
 
 Use:
 
@@ -31,3 +55,14 @@ fclt ai evolve promote EV-00001 --to global --project
 ```
 
 That creates a new global proposal for review. It does not auto-apply the promotion.
+
+## Decision Checklist
+
+Choose project when the answer depends on "this repo". Choose global when the answer would still be correct after removing the repo name.
+
+If unsure:
+
+1. keep the asset project-scoped
+2. record writeback with the reason it might generalize
+3. wait for another project or repeated evidence
+4. promote through a reviewable proposal, not by copying files by hand

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

@@ -9,6 +9,8 @@ A work unit is the smallest coherent unit of agent work that can be understood,
 
 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.
 
+Use work units for ordinary work, not only for capability updates. Coding changes, research answers, documentation edits, operational triage, setup repair, design reviews, and capability evolution all benefit from the same shape when the task has real uncertainty or risk.
+
 ## Minimum Contract
 
 A well-formed work unit names:
@@ -24,6 +26,8 @@ A well-formed work unit names:
 
 If one of these is missing and the gap blocks correctness, surface the gap early and recover it before moving faster.
 
+For low-risk one-step work, keep the contract implicit. For ambiguous, high-impact, cross-tool, stateful, or multi-step work, make the contract explicit before executing.
+
 ## Why It Exists
 
 Work-unit framing prevents shallow completion. It helps agents avoid:
@@ -34,6 +38,9 @@ Work-unit framing prevents shallow completion. It helps agents avoid:
 - creating duplicate tasks or proposals
 - turning one-off preferences into global rules
 - pushing project-specific details into global capability
+- producing output faster than the system can review, integrate, or learn from it
+
+The point is not paperwork. The point is to attach machine work to intent, context, evidence, and memory so that useful learning can change future work instead of disappearing into chat history.
 
 ## How To Use It
 
@@ -54,6 +61,47 @@ Writeback:
 
 Use the smallest framing that makes the task correct. Do not turn every request into paperwork.
 
+## Examples
+
+Coding:
+
+```text
+Goal: fix the failing login test
+Acceptance: test passes and no auth regression is introduced
+Context: failing test output, auth middleware, recent commits
+Constraints: preserve public API
+Evidence: focused test, relevant integration test
+Artifact: code diff and concise summary
+Verification: command output and changed behavior
+Writeback: only if the failure exposes stale test or auth guidance
+```
+
+Research:
+
+```text
+Goal: answer a source-backed product question
+Acceptance: answer cites current primary sources
+Context: user question, relevant docs, dates
+Constraints: distinguish verified facts from inference
+Evidence: source links and quotes within fair-use limits
+Artifact: answer or research note
+Verification: source freshness and consistency check
+Writeback: durable note if the finding will recur
+```
+
+Capability evolution:
+
+```text
+Goal: decide whether repeated writebacks justify a proposal
+Acceptance: proposal exists only if evidence repeats or a capability is clearly missing
+Context: grouped writebacks, target asset, current canonical guidance
+Constraints: avoid global noise and private leakage
+Evidence: writeback IDs and affected work units
+Artifact: accepted proposal, rejected proposal, or no-op note
+Verification: proposal kind, scope, target, and review artifact
+Writeback: only for new meta-learning about the evolution process
+```
+
 ## Writeback
 
 When the work reveals durable friction, missing capability, stale guidance, or a repeatable workflow, prefer one strong writeback over many weak ones.

package/assets/packs/facult-operating-model/skills/capability-evolution/SKILL.md

@@ -12,6 +12,8 @@ Do not wait for a human operator by default if the signal is already clear and t
 
 Use 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.
 
+The goal is a governed feedback loop: work creates evidence, evidence produces writeback, repeated writeback becomes a small reviewed proposal, and accepted proposals change future agent behavior.
+
 ## Scope Decision
 
 Choose `project` when the behavior depends on repo-local architecture or workflow.
@@ -20,14 +22,17 @@ Choose `global` when the behavior is broadly reusable.
 
 If unsure, start at project scope and promote later with evidence.
 
+Reject global scope when the proposal depends on private examples, one repo's architecture, a single user's temporary preference, or a workflow that has not repeated.
+
 ## Working Flow
 
-1. record the strongest writeback
-2. group or summarize repeated signal
-3. choose the smallest valid proposal kind
-4. draft the proposal
-5. accept only after the target and scope are correct
-6. apply only when the markdown target is the intended canonical asset
+1. Read current writebacks and existing proposals.
+2. Group or summarize repeated signal by asset, kind, and scope.
+3. Check the current target asset before proposing a change.
+4. Choose the smallest valid proposal kind.
+5. Draft the proposal with evidence and intended target.
+6. Accept only after the target and scope are correct.
+7. Apply only when the markdown target is the intended canonical asset.
 
 Use:
 
@@ -52,6 +57,8 @@ fclt templates init automation tool-call-audit
 
 If there is not yet enough repeated signal for evolution, record the writeback and stop there.
 
+Do not create a proposal only to preserve an idea. Preserve the idea as writeback, notes, or task tracking unless it has enough evidence to change capability.
+
 ## Proposal Kind Selection
 
 - `update_asset` for tightening existing guidance
@@ -62,9 +69,21 @@ If there is not yet enough repeated signal for evolution, record the writeback a
 
 Use 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.
 
+## Review Criteria
+
+Before accept/apply, verify:
+
+- evidence is repeated or the missing capability is obvious
+- the proposal targets the smallest affected unit
+- project/global scope is correct
+- private or project-specific examples are not leaking into global assets
+- the patch changes canonical markdown assets, not generated runtime state
+- the resulting behavior can be verified by reading, rendering, indexing, or running the relevant command
+
 ## Output Contract
 - repeated signal
 - proposed asset change
 - target scope
 - evidence
 - smallest useful next step
+- approval or no-op rationale

package/assets/packs/facult-operating-model/skills/project-operating-layer-design/SKILL.md

@@ -8,8 +8,41 @@ tags: [facult, project, design]
 ## When To Use
 Use this skill when a project needs its own `.ai/` structure, repo-specific instructions, or local bootstrap guidance.
 
+Use it when:
+
+- a repo has recurring agent friction that should not become global doctrine
+- setup or verification steps are repeatedly rediscovered
+- project skills, agents, MCP definitions, or snippets need a stable source of truth
+- a repo needs policy for what may be rendered into tool homes
+- a project should contribute writeback/evolution evidence without committing private review artifacts
+
+Do not use it to copy a user's private global preferences into a public repo.
+
+## Design Rules
+
+- Start from the repo's real workflows, commands, and risk boundaries.
+- Keep project-specific guidance in `<repo>/.ai`.
+- Keep generated state, queues, review artifacts, and local machine config out of the repo.
+- Prefer a few high-leverage instructions or skills over a large generic dump.
+- Use snippets only for blocks that are reused or independently evolvable.
+- Make verification and integration paths explicit enough for future agents to run.
+- Add sync policy only for assets that should render into repo-local tool outputs.
+
+## Working Flow
+
+1. Inventory existing repo guidance and tool files.
+2. Identify repeated friction from recent work, issues, reviews, or writebacks.
+3. Separate project-specific behavior from global/user-owned behavior.
+4. Propose a minimal `.ai` layout.
+5. Add or update the smallest useful assets.
+6. Verify the graph/index and any rendered output.
+7. Record writeback for reusable learnings that should evolve later.
+
 ## Output Contract
 - recommended `.ai/` layout
 - what stays project-local
 - what stays global
 - what should remain generated runtime output only
+- sync/rendering policy
+- verification path
+- privacy or commit-safety risks

package/assets/packs/facult-operating-model/snippets/global/core/feedback-loops.md

@@ -6,5 +6,6 @@
 - Treat verification, evaluation, and writeback as part of the work, not cleanup after it.
 - For work-unit clarification, read ${refs.work_units}.
 - For verification guidance, read ${refs.verification}.
+- For integration risk, read ${refs.integration}.
 - For learning and writeback, read ${refs.learning_writeback}.
 - For deeper guidance, read ${refs.feedback_loops}.

package/assets/packs/facult-operating-model/snippets/global/core/work-units.md

@@ -1,6 +1,7 @@
 - Treat every task as a work unit, not just a request.
-- A work unit should have a goal, acceptance criteria, required context, constraints, signals or evidence, an output artifact, and a verification path.
+- A work unit should have a goal, acceptance criteria, required context, constraints, signals or evidence, an output artifact, a verification path, and a writeback target when the work teaches something reusable.
 - If any of those are missing and the gap blocks correctness, surface it early and try to recover it.
 - Prefer making the work unit more explicit before increasing execution speed.
 - If the task is vague, ambiguous, or overloaded, narrow it before acting.
+- Treat work-unit framing as generally applicable to coding, research, writing, operations, setup, debugging, and capability evolution.
 - For deeper guidance, read ${refs.work_units}.

package/assets/packs/facult-operating-model/{AGENTS.global.md → snippets/templates/agents-global.md}

@@ -1,5 +1,10 @@
 # Global Agent Instructions
 
+This template materializes as `AGENTS.global.md` when the operating-model pack is
+installed. It should stay small and composed from snippets. Put detailed
+doctrine in instructions, workflow execution in skills, and local/private
+preferences in user-owned or project-owned assets outside the public pack.
+
 ## Working mode
 
 <!-- fclty:global/baseline -->
@@ -22,6 +27,7 @@
 - For work-unit definition and scope clarification, read ${refs.work_units}.
 - For identifying, improving, and validating feedback loops, read ${refs.feedback_loops}.
 - For verification and anti-false-positive checks, read ${refs.verification}.
+- For checking integration boundaries, read ${refs.integration}.
 - For learning, decisions, and writeback, read ${refs.learning_writeback}.
 - For capability evolution, proposal kinds, and `facult ai` workflow, read ${refs.evolution}.
 - For deciding whether something belongs in global or project scope, read ${refs.project_capability}.

package/docs/README.md

@@ -9,9 +9,12 @@ The concepts guide includes the [feedback-loop diagram](./assets/fclt-capability
 ## Guides
 
 - [Concepts](./concepts.md): canonical roots, generated state, rendered outputs, scopes, and asset types.
+- [Work Units](./work-units.md): a general frame for agent work, evidence, verification, and writeback.
 - [Composable Capability](./composable-capability.md): refs, snippets, instruction templates, and evolvable units.
 - [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.
+- [Built-in pack upgrades](./pack-upgrades.md): non-destructive refresh behavior for existing `.ai` roots.
+- [Codex plugin](./codex-plugin.md): installable Codex skills and MCP tools for fclt workflows.
 - [Writeback and evolution](./writeback-evolution.md): how real-work friction becomes reviewable capability changes.
 - [Managed mode](./managed-mode.md): when to let `fclt` write tool files, and how adoption works.
 - [Security and trust](./security-trust.md): source trust, audit, secrets, and commit hygiene.
@@ -24,6 +27,7 @@ The concepts guide includes the [feedback-loop diagram](./assets/fclt-capability
 New users should read:
 
 - [Concepts](./concepts.md)
+- [Work Units](./work-units.md)
 - [Project `.ai`](./project-ai.md) if working in a repo
 - [Managed mode](./managed-mode.md) only before allowing `fclt` to write tool files
 - [Writeback and evolution](./writeback-evolution.md) before setting up feedback loops

package/docs/built-in-pack.md

@@ -31,9 +31,19 @@ Agents:
 - `scope-promoter`
 - `integration-auditor`
 
-Global doc:
+Entry template:
 
-- `AGENTS.global.md`
+- `snippets/templates/agents-global.md`
+
+The template materializes as `AGENTS.global.md` when installed into a canonical `.ai` root. The source lives under snippets/templates so the pack itself models composition instead of treating the root global doc as a special hand-maintained asset. The installed `AGENTS.global.md` should stay small and point to snippets and instructions rather than becoming the only place where guidance lives.
+
+On first install, `fclt` preserves existing guidance when it can:
+
+- global installs seed `AGENTS.global.md` from existing global agent docs such as `~/.codex/AGENTS.md` or `~/.claude/CLAUDE.md`
+- project installs seed from the repo's existing `AGENTS.md` or `CLAUDE.md`
+- the packaged template is only the fallback when no existing guidance is found
+
+Seeded `AGENTS.global.md` files are treated as user-owned. They are not marked as pack-owned in the update manifest, so future `--update` runs skip them instead of replacing them with the fallback template.
 
 ## When It Becomes Active
 
@@ -53,6 +63,15 @@ 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.
 
+Refresh an existing root non-destructively:
+
+```bash
+fclt templates init operating-model --global --update --dry-run
+fclt templates init operating-model --global --update
+```
+
+`--update` refreshes only files that still match the last installed pack manifest and skips local edits. See [Built-in pack upgrades](./pack-upgrades.md).
+
 Use `project-ai` when the target is the current repo:
 
 ```bash
@@ -95,5 +114,7 @@ Keep project-specific behavior in project `.ai`. Promote it only when repeated e
 ## Next
 
 - Read [Composable Capability](./composable-capability.md) for refs, snippets, and instruction templates.
+- Read [Work Units](./work-units.md) for the general work-unit model.
+- Read [Built-in pack upgrades](./pack-upgrades.md) before refreshing an existing root.
 - Read [Writeback and evolution](./writeback-evolution.md) for the feedback loop.
 - Read [Managed mode](./managed-mode.md) before rendering the pack into a tool home.

package/docs/codex-plugin.md

@@ -0,0 +1,57 @@
+# Codex Plugin
+
+`fclt` ships a first-party Codex plugin at:
+
+```text
+plugins/fclt/
+```
+
+The plugin is for agent-led operation. After install, Codex gets focused skills for setup, writeback, evolution, and capability review, plus an MCP server wrapper that exposes common `fclt` CLI actions as tools.
+
+## What It Includes
+
+- `fclt-setup`: install, update, inspect, initialize, and repair fclt setup.
+- `fclt-writeback`: record and review durable writebacks from real work.
+- `fclt-evolution`: turn repeated writeback into reviewed capability proposals.
+- `fclt-capability-review`: inspect global/project capability roots and scope changes.
+- `fclt` MCP server: stdio wrapper around the installed `fclt` CLI.
+
+The MCP wrapper intentionally delegates to the local `fclt` binary instead of duplicating core logic. Set `FCLT_BIN` if Codex should call a specific binary.
+
+## MCP Tools
+
+The plugin exposes:
+
+- `fclt_status`
+- `fclt_doctor`
+- `fclt_paths`
+- `fclt_init_operating_model`
+- `fclt_writeback_add`
+- `fclt_writeback_review`
+- `fclt_evolve`
+
+These tools are thin wrappers around CLI commands and return command output. Mutating tools still rely on the normal fclt safety model: dry-run first when available, review broad changes before apply, and preserve existing user guidance.
+
+## Install In Codex
+
+From this repository, the plugin can be rendered into the Codex plugin marketplace by managed sync:
+
+```bash
+fclt manage codex --global
+fclt sync codex --global
+```
+
+That writes plugin files under the Codex plugin location and updates the personal marketplace entry. Use managed sync only when you want `fclt` to write Codex tool files.
+
+For local plugin development, run the lightweight checks that ship with the repository:
+
+```bash
+node plugins/fclt/scripts/fclt-mcp.js --self-test
+bun run check
+```
+
+## Recommended Agent Use
+
+Use the plugin skills as the first interface. Use MCP tools when a Codex workflow benefits from structured calls for status, doctor, paths, writeback, or evolution review.
+
+Do not create writeback/evolution noise. Record strong signal, group repeated signal, then propose the smallest concrete capability change.

package/docs/concepts.md

@@ -48,7 +48,9 @@ Use these as installable catalog sources. Review and trust source policy before
 
 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.
+This applies to ordinary coding, research, docs, operations, setup, and debugging work, not only to skill or instruction updates. Agents should keep this implicit for simple work and make it explicit when the task is ambiguous, risky, stateful, 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.
+
+See [Work Units](./work-units.md) for the detailed model.
 
 ## State Layers
 
@@ -133,3 +135,4 @@ The durable loop is:
 - Read [Project `.ai`](./project-ai.md) before adding repo-local capability.
 - Read [Managed mode](./managed-mode.md) before allowing `fclt` to write tool files.
 - Read [Composable Capability](./composable-capability.md) to split guidance into instructions, snippets, skills, agents, MCP, and automations.
+- Read [Work Units](./work-units.md) to understand the general task frame behind writeback and evolution.