@iowarp/clio-coder 0.4.6 → 0.4.7

package/docs/architecture/worker-context.md

@@ -0,0 +1,106 @@
+# Worker context inheritance
+
+> **Visual blueprint:** [Worker context visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/worker_context_blueprint.html).
+
+Clio dispatch separates **what a worker inherits** from **how workers are scheduled**. This implements the isolation, fork, and splice patterns discussed in [Organizing context in a multi-agent harness](https://www.langchain.com/blog/organizing-context-in-a-multi-agent-harness), using Clio's existing Pi agent loop and dispatch admission boundary.
+
+The default remains an isolated conversation. A native worker gets its own Pi Agent, worker system prompt, admitted tools, dynamic project context, task, and run-local accounting. Context inheritance does not grant additional tools, write roots, or autonomy. Conversation isolation is not a filesystem sandbox; use dispatch worktrees when filesystem isolation is required.
+
+## Dispatch API
+
+```json
+{
+  "agent": "researcher",
+  "task": "Investigate the parser failure and cite the relevant source lines.",
+  "intent": { "read_roots": ["src/parser"] },
+  "context": { "mode": "splice", "paths": ["src/parser"], "max_tokens": 8000 }
+}
+```
+
+`context` is independent of the top-level scheduling `mode` (`parallel`, `sequential`, `pipeline`, and so on). A batch's `context` is the default for each task; an object task can replace it, for example with `{ "mode": "isolated" }` for a separate check. Ordinary `briefing` and pipeline predecessor outputs remain separate dynamic inputs.
+
+| Context mode | Native HTTP/Pi worker | ACP and other runtimes | Selection |
+| --- | --- | --- | --- |
+| `isolated` | Fresh conversation | Fresh runtime conversation | No inherited session messages; existing project context and explicit briefing still apply |
+| `fork` | Existing history seeded into Pi | Rejected; use splice | Entire captured model-visible history, without silent trimming |
+| `splice` | Bounded historical evidence packet | Same packet through existing prompt delivery | Exact selected text, with source labels; no summarizer or extra model call |
+
+Fork accepts optional `max_tokens`. Splice also accepts `paths` and `refs`. The token limit is an estimate for the inherited portion, not the complete worker request. The final request must also fit the worker's system prompt, tool schemas, task, dynamic inputs, and output reserve. The allowed explicit token range is 256-262144; the default splice limit is 8000. A seed has a 512 KiB serialized cap, and the complete native WorkerSpec must fit the existing 1 MiB stdin frame. Larger contexts fail explicitly.
+
+Splice refs address the captured messages: `tool:<call-id>` for a tool result, or `message:<zero-based-index>` for a user or assistant message. Unknown refs fail. Ref indexes are snapshot-relative, not session turn IDs. Path selection is the practical default: explicit paths override the intent's read roots, relevant paths, and write roots. Matching uses lexical paths in tool arguments relative to the parent's workspace; it does not read files, follow symlinks, or perform semantic relevance search. Without paths, recent tool observations are candidates.
+
+All parent user/context text, tool errors, and explicit refs are required. If they cannot fit, dispatch refuses the splice and asks for a larger budget or an isolated task with an explicit briefing. Optional observations are selected newest first, then rendered in original order. Repeated calls with identical names and arguments use the newest optional observation; a smaller stale result cannot replace a newer result that did not fit. Assistant conclusions enter only through explicit refs and are labeled as parent claims. Private reasoning is omitted from splices. Required user images and explicitly selected image results require native fork; optional image observations are omitted and the packet discloses that it contains selected text only.
+
+## Capture, ownership, and reproducibility
+
+The chat loop captures its current Pi messages, or its prepared model replay when no runtime is active. This is the active branch's model-visible working set: existing compaction and eviction projections stay in effect. It does not reopen the raw parent ledger or resurrect sibling branches.
+
+Capture occurs synchronously when dispatch arguments are admitted, before asynchronous routing, metadata probes, permission handling, or execution. Every inheriting member of one dispatch call uses the same capture boundary. A final incomplete assistant tool-call batch, including any results already completed within that batch, is excluded as a unit. Capture also follows Pi's exclusion of aborted and errored assistant responses, drops results belonging to their partial tool declarations, and records the excluded count. User instructions survive that filtering. An orphaned result, duplicate tool-call ID, or incomplete older batch causes explicit refusal rather than constructing invalid provider history.
+
+The snapshot is deeply copied. Admission freezes selected requests, and retries and detached execution carry the selected seed rather than rereading the parent. Pipeline steps receive their upstream result separately; later parent turns do not become part of the already admitted seed. Separate dispatch calls have separate capture boundaries. Automatically constructed reviewers and judges retain their own fresh requests; do not use inherited author conclusions when an independent check is the purpose of a separately dispatched worker.
+
+Native forks enter `initialState.messages`. They are not replayed as new events, credited as worker token usage, or counted as reads and tests executed by the worker. Pi remains responsible for converting model-specific messages at the provider boundary. A splice enters once through dynamic prompt messages. The worker's own assignment comes after inherited context and dynamic inputs.
+
+The parent session writer is never forked or closed. Human `/tree`, `/fork`, and resume retain their existing semantics. Workers do not append their raw conversations to the parent; dispatch continues to return the normal sealed worker result.
+
+## Context pressure and recovery
+
+Every native worker checks context headroom before each provider request. The estimate includes actual system and tool surfaces and reserves output capacity. It honors the configured compaction threshold and automatic working-set eviction setting. Parent usage is never a sizing anchor for a child; after the worker's first completion, its own provider usage calibrates subsequent estimates.
+
+The first request is never automatically reduced: an oversized fork must be explicitly replaced by a smaller splice. During later requests, the guard preserves the two most recent assistant rounds and all user context, tool errors, mutations, and unknown tools. It may remove older private reasoning when visible assistant content remains, and replace large older successful observations from known read tools with stable markers. The original Pi history is not rewritten.
+
+Evicted observations are durably stored before replacement under `$XDG_STATE_HOME/clio-coder/context-observations/<digest>.json` (or Clio's configured state root). A marker provides an exact file location and a `worker:<digest>` recall ref. Native `context(scope="recall")` discovers only this run's evicted observations. Passing a ref retrieves the exact persisted result through the existing bounded observation envelope. The run-local allowlist rejects another worker's refs, arbitrary paths, and parent-session refs; stored bytes are digest-checked on recall. Recall does not count as rereading or validating the current source. Workers without an admitted context tool can use the marker's file through their admitted read tool.
+
+If protected context still cannot fit, the worker ends with `worker_context_exhausted`. Dispatch classifies that as deterministic and does not retry it unchanged. Backend token counts can differ from structural estimates; the guard is conservative headroom management, not a promise that every provider tokenizer or oversized individual tool response will fit.
+
+## Evidence and compatibility
+
+Non-isolated requests record context mode, parent session/leaf/workspace, snapshot digest, selected-content digest, estimated tokens, bytes, selected refs, omitted messages, the excluded unfinished tail, and excluded interrupted responses. The resolved plan displays the selection's digest and size; the run envelope and receipt carry the provenance under `workerContext`. Receipt integrity binds it, and context provenance remains separate from independent validation evidence.
+
+The host persists the selected seed at `$XDG_STATE_HOME/clio-coder/context-seeds/<contentHash>.json`, using mode 0600 and durable writes. These are exact historical artifacts with the same sensitivity as session history; no automatic garbage collection is introduced in this change. Native seeds are self-contained over the wire, including for remote workers. Their metadata and contents are validated before model use and are covered by the existing whole-spec attestation.
+
+WorkerSpec version **4** is required. Rebuild/update remote workers together with the orchestrator; an older worker must reject the new specification rather than silently ignore inherited history. ACP and other runtime adapters receive bounded splice text but do not implement native history forking or Clio's native pressure/recall loop.
+
+No extra LLM request is needed for capture or selection. Optional splice budgeting uses additive size estimates and one final serialization, rather than serializing the growing packet for every candidate. Stable projections help repeated requests retain an unchanged prefix, but provider cache reuse is measured behavior, not guaranteed: worker system prompts, tool surfaces, models, and provider cache rules can differ from the parent.
+
+## A worker's output token limit
+
+A worker is a separate process. It does not inherit the parent session's live
+settings; it reads layered settings from disk for its own working directory
+(`startWorkerRun`, `src/engine/worker-runtime.ts`). An unsaved `/settings` or
+`/model` override in the parent session therefore does not reach it. Those
+resolved settings also govern the worker's observation caps and working-set
+eviction, not just its output cap. External vendor runtimes, such as Claude CLI
+or Antigravity delegation, return before this native path and are not governed by
+the native request adapter at all.
+
+Precedence for `chat.maxOutputTokens`, highest first: `.clio-coder/settings.local.yaml`,
+`.clio-coder/settings.yaml`, the user `settings.yaml`, then the compiled default.
+**The compiled default is `0`** (`src/core/defaults.ts`), which is not a token
+count. `0` means "use the resolved model's advertised output limit", falling back
+to the product floor when the model does not advertise one.
+
+Both project layers are gated on workspace trust (`src/core/workspace-trust.ts`).
+An untrusted project, a project whose configuration changed after trust was
+recorded, or a malformed settings file all drop the project layers and fall back
+to user settings or the compiled default. This is why a worker can legitimately
+run with a different cap than the project file appears to ask for.
+
+Whatever the resolved number is, it is a request, not a promise. `remainingContextMaxTokens`
+(`src/engine/apis/output-budget.ts`) clamps it to the model's advertised output
+limit and to the remaining context window, and each provider then maps the budget
+onto its own wire contract. On the OpenAI-compatible LiteLLM path,
+`reasoning_effort` is forwarded under `allowed_openai_params` when thinking
+effort is enabled (`src/engine/apis/openai-completions.ts`); that is a LiteLLM
+compatibility allowance and not a universal provider contract. A per-response cap
+also caps one response, not a task: it does not bound total task tokens or
+guarantee the task finishes.
+
+`tests/contracts/worker-output-settings.test.ts` covers the eight combinations of
+trust state and layer (trusted project at low/medium/xhigh effort, trusted local
+override, untrusted, changed-after-trust, malformed, and user settings only).
+
+## Validation
+
+The worker-context contract tests cover incomplete multi-tool batches, copy isolation, path and explicit-ref selection, stale duplicate reads, mandatory constraints and errors, images, admission freezing, active-branch eviction replay, receipt tampering, scoped recall, and provider-usage reconciliation after eviction. Dispatch integration tests run the actual Pi worker against a controlled HTTP provider and verify single delivery, exclusion of later parent turns, absence of inherited fork events, wire validation, and rejection before a provider call when context is oversized. The normal full CI gate also exercises existing dispatch, session replay, worker transport, and operator behavior.
+

package/docs/guide/authoring-plugins.md

@@ -0,0 +1,160 @@
+# Authoring a portable agent plugin
+
+> **Visual blueprint:** See the [visual reference](../html/authoring_plugins_blueprint.html) in the source checkout.
+
+An agent plugin packages a workflow and its supporting resources as one versioned installation. Its canonical identity is the [Agent Plugins 1.0.0 manifest](https://agent-plugins.org/schemas/1.0.0/plugin.schema.json). Clio keeps the complete package together, verifies its full-tree digest, and discovers the resources supported by the current runtime.
+
+The minimal package has a root `plugin.json` and an immediate child skill directory:
+
+```text
+lab-research/
+  plugin.json
+  skills/
+    research/
+      SKILL.md
+```
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "lab-research",
+  "version": "1.0.0",
+  "description": "Research from supplied lab evidence"
+}
+```
+
+Portable identity and publisher metadata remain at the root. The root schema permits `$schema`, `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`, and `extensions`. Names have 1 to 64 lowercase letters, digits, hyphens or periods, begin and end with an alphanumeric character, and contain neither `--` nor `..`. Clio reserves `state.json` as an installation bookkeeping name. Every package, including a local authoring install, requires an explicit Semantic Version. Numeric prerelease identifiers cannot contain leading zeros.
+
+## Native Clio components
+
+`extensions["ai.iowarp.clio"]` holds optional Clio metadata inside the portable manifest. A plugin containing `skills/<name>/SKILL.md` needs only the root identity fields above: Clio discovers the conventional `skills/` directory. A standalone skill package with a root `SKILL.md` declares `kind: "skill"`, `resources.skills: "."` and its one public skill component through the extension; the supplied skill template demonstrates that form. Clio prompts, strict agent recipes, fleets and explicit component graphs also use this metadata. The key does not select a directory: its `resources` map names the paths the package actually uses.
+
+Use `extensions["ai.iowarp.clio"]` as the manifest metadata key to declare Clio prompts, strict agent recipes, and fleets. In modern packages, resources use ordinary top-level directories (`agents/`, `prompts/`, `skills/`, `fleets/`), while `assets/` holds shared supporting files. (Historical bundles such as `materio` may nest resources under `ai.iowarp.clio/` for backward compatibility, but top-level directories are recommended for new packages.)
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "lab-research",
+  "version": "1.0.0",
+  "description": "Research from supplied lab evidence",
+  "extensions": {
+    "ai.iowarp.clio": {
+      "manifestVersion": 1,
+      "compatibility": { "clio": ">=0.4.7" },
+      "resources": {
+        "skills": "skills",
+        "prompts": "prompts",
+        "agents": "agents"
+      },
+      "components": [
+        {
+          "kind": "resource",
+          "id": "methods",
+          "path": "assets/methods.md"
+        },
+        {
+          "kind": "skill",
+          "id": "research",
+          "path": "skills/research/SKILL.md",
+          "requires": ["resource:methods"]
+        },
+        {
+          "kind": "agent",
+          "id": "researcher",
+          "path": "agents/lab-research-researcher.md",
+          "requires": ["skill:research"]
+        },
+        {
+          "kind": "prompt",
+          "id": "start",
+          "path": "prompts/lab-research/start.md",
+          "requires": ["agent:researcher"]
+        }
+      ]
+    }
+  }
+}
+```
+
+Create every declared directory and file before validation. Resource kinds are `skills`, `prompts`, `agents`, `fleets`, and `themes`. Component kinds are `skill`, `prompt`, `agent`, `fleet`, `script`, `resource`, and `tool`. A component has a stable `kind:id` identity, one contained file path, and optional `requires` references to other components in the same bundle. A skill points to its `SKILL.md`. Dependencies must exist and form an acyclic graph. Native discoverable components must live beneath their declared resource root. Component metadata records relationships; it does not execute scripts or register tool implementations.
+
+Clio text can refer to `${pluginRoot}/assets/methods.md` or `${component:resource:methods}`. Prompts, agent bodies, and skills recognize prose markers with portable, space-free slash suffixes. For a filename containing spaces or Unicode, declare a component and refer to its `kind:id`. The referenced target must exist within the declaring package. Fleet argument paths use a separate complete-path parser: the reference must occupy the whole argument, and containment is checked after expanding the entire suffix, including spaces and Unicode. A reference embedded in an option such as `--file=${pluginRoot}/data.csv` is rejected; pass the path as its own argument. These are Clio reference forms; peer exports translate instructions and paths for their native host. Portable skill text should use relative file references where practical.
+
+Prompt names follow their path beneath the prompts root. The example exposes `/lab-research:start`. Give agent and fleet filenames a package prefix to keep their registered identities unambiguous. Agent recipes retain the strict version 1 contract, including required and optional tool lists, custom audience, budget, and result contract. Recipes bind skills from their own package. Interviews belong to the orchestrator; a worker returns its need for input and is redispatched after the researcher answers.
+
+## Validation and lifecycle
+
+```bash
+clio-coder library validate ./lab-research --json
+clio-coder library inspect ./lab-research --json
+clio-coder library install ./lab-research --project
+clio-coder library list --all --json
+clio-coder library drift lab-research --project
+```
+
+`library validate <package-path> --json` performs a read-only content and payload validation before any installation or registration:
+- **Manifest validity**: Parses `plugin.json` against the schema, verifying identifiers, SemVer compliance, and declared resource roots.
+- **Payload & schema validation**: Validates agent recipes against strict v1 schemas, policy budgets, and custom audience rules; parses fleet DAGs, loop boundaries, and write boundaries; and checks prompt loadability.
+- **Package reference resolution**: Ensures all `${component:...}` and `${pluginRoot}` references point to existing files within the package boundary and form an acyclic graph.
+- **Prerequisite separation**: Reports required external commands or core agents as environment prerequisites rather than failing package content validity.
+- **Read-only**: Leaves package files, repository files, and installation state roots completely unchanged.
+
+Installation validates the exact manifest bytes included in the tree digest, copies into private staging, verifies that source and staging still match, and publishes the package and installation record with rollback on failure. Pins bind filenames, entry kinds, bytes, symlink targets and empty directories. Escaping links, hard links, unsupported filesystem entries and a root `state.json` are rejected. A catalog's expected identity, version and digest cannot be bypassed with `--force`.
+
+User installations live in the Clio configuration directory's `plugins/`; project installations live in `.clio-coder/plugins/`. State is outside the bundle, in the parent `state.json`. Installations also retain their source origin for updates. A valid project copy takes precedence over the user copy; disabling that project copy suppresses both. Changed or unverifiable content cannot load or be enabled. Update refuses local drift unless explicitly forced, and replacement or removal preserves changed files in a reported recovery copy.
+
+An active session observes additions and replacements after `/library reload` or restart. Removal, disabling and digest drift revoke subsequent resource discovery even when an earlier snapshot remains committed. Executable harness tool schemas have a separate lifecycle and require a new session after changes.
+
+## Host projections and runtime capabilities
+
+Agent Plugins 1.0.0 standardizes skills and MCP declarations. Clio currently consumes portable skills and its native manifest extension; it preserves MCP files but does not execute MCP servers. Claude Code and Gemini have their own native manifests and component formats. A package exporter must translate those formats and report which features are native, adapted as instructions, or unavailable. An exported skill workflow does not establish that a peer host executes Clio fleets.
+
+The bundled `materio` plugin includes a tested Python exporter for Codex, Claude Code and Gemini. See its package README for commands and capability reports. It also provides a complete worked example of explicit component relationships and shared domain references.
+
+Two layouts need no exporter at all, because Claude Code and Codex load them directly from the unchanged package:
+
+- A standalone skill package with a root `SKILL.md`, no `skills/` directory and no top-level `skills` manifest field. Claude Code loads it as a single-skill plugin and takes the invocation name from the `SKILL.md` frontmatter. Codex finds the same directory under any of its skills roots.
+- A bundle with a real `skills/` directory. Both hosts publish exactly those skills.
+
+What a peer host does *not* load matters just as much. Claude Code scans a plugin root for `agents/`, `commands/`, `hooks/`, `output-styles/` and `.mcp.json` with no manifest asking it to. A Clio strict-v1 recipe sitting in a top-level `agents/` directory is therefore picked up and shown as a native Claude agent, tools, model and budget fields included, none of which that host honors. Clio `prompts/` and `fleets/` are inert to it.
+
+That leaves a real choice when a package should serve both audiences. Ordinary top-level `agents/` and `prompts/` directories are the recommended Clio layout and stay a valid first-class library package; the repository marketplace simply does not publish such a package, and `pnpm run library:pin` prints the reason. To publish it as well, declare its Clio resource roots at paths no peer host scans, for example `"agents": "native/agents"` in the manifest's `resources` map, and put the recipes there. The bundled `materio` package does this with its own historical directory name.
+
+Keep the skill surface intact when you edit a package: adding a `skills/` directory to a standalone skill silently stops its root `SKILL.md` from loading. `tests/contracts/library-portability.test.ts` asserts all of this for every curated package, and `scripts/verify-portable-hosts.sh` re-measures it against the real host CLIs. See [coding agent interoperability](interop.md) for the exact install commands.
+
+Harness extensions register runtime tools through the [harness extension contract](harness-extensions.md). They use a separate extension manifest and installation state, and they cannot declare domain resources: prompts, agents, skills, fleets and reference files ship in a plugin. See [plugin library usage](plugins.md) for catalogs, updates, pins and terminal UI operations.
+
+## Authoring templates and contributor journey
+
+Clio Coder provides working, valid authoring templates for all five package kinds in `library/_authoring/templates/`:
+
+- `library/_authoring/templates/skill/`: Standalone skill with house conventions, triggers, and recorded eval scenarios.
+- `library/_authoring/templates/agent/`: Standalone agent recipe using strict v1 fields, `skills: []`, and `audience: custom`.
+- `library/_authoring/templates/prompt/`: Parameterized prompt with path-derived invocation (`/<name>`) and `$ARGUMENTS` expansion.
+- `library/_authoring/templates/fleet/`: Multi-agent coordination contract with a valid DAG and documented prerequisites.
+- `library/_authoring/templates/plugin/`: Composite bundle showing an agent binding a contained skill, prompts, and supporting assets.
+
+Templates are reference models and are excluded from `library/registry.yaml`. Follow this unified contributor journey:
+
+1. **Choose package kind**: Decide whether your package is a single-kind package (`skill`, `agent`, `prompt`, `fleet`) exposing exactly one public recipe, or a composite `plugin` bundle combining multiple resources.
+2. **Copy authoring template**: Copy from `library/_authoring/templates/<kind>/` into your project or repository.
+3. **Author resources**:
+   - Single-kind packages expose exactly one public resource file in their declared resource directory (`skills`, `agents`, `prompts`, or `fleets`).
+   - Keep `README.md` at the package root, outside the resource directory, so the loader does not discover it as a second public recipe.
+   - Packages may carry explicitly invoked scripts (e.g., for offline evaluation or verification tasks); these are declared metadata and are strictly distinct from harness extensions, which register runtime tools and hooks.
+4. **Validate**:
+   Run `clio-coder library validate ./lab-research --json` to verify manifest schemas, resource payloads, reference syntax, and loadability.
+5. **Pin and check**:
+   Maintainers run `pnpm run library:pin` and `pnpm run library:check` to refresh and verify full-tree distribution pins. For curated skills, maintainers also run `pnpm run skills:pin` and `pnpm run skills:check`.
+   - **Full-tree pins** (`library/registry.yaml`) cover every distributed byte to verify package integrity.
+   - **Normalized skill evidence** (`library/skills/registry.yaml`) records normalized skill body hashes as provenance evidence for reviewed instructions.
+6. **Try in isolated project**:
+   Register locally with `clio-coder library register ./lab-research --project`. Registration writes identity, version, source, and full-tree SHA-256 into the scoped `library.yaml`. Preview and install with `library install plugin:lab-research --project --dry-run`, then `library install plugin:lab-research --project`. Test invocation through `/skills`, `/run`, prompt slash commands, or `/fleet run`.
+7. **Submit a focused fork PR**:
+   Push your topic branch to your fork and submit a PR against `main`.
+
+Package dependencies live in `extensions["ai.iowarp.clio"].requires`, such as `["skill:ship"]`; copy the same requirements into the index. They name packages, while component `requires` names files within one package. Neither declares an execution hook.
+
+Declare runnable eval suites using `"evals": {"scripts": "evals/scripts.yaml"}` in the Clio extension. Paths must identify contained files. Validate with `clio-coder eval validate --package ./lab-research --eval scripts` and run with `clio-coder eval run --package ./lab-research --eval scripts`. Use the standard version-2 eval suite schema. Materio's [worked suite](../../library/plugins/materio/evals/scripts.yaml) runs Python contracts in a temporary package copy; package installation never runs evals.
+
+See [Library packages](resource-library.md) for every lifecycle command and [Library architecture](../architecture/library.md) for identity, trust, pin and namespace invariants.

package/docs/guide/built-in-agents.md

@@ -16,7 +16,7 @@ Clio's agent architecture distinguishes between authoring configurations and run
 *   **Recipe**: An authored Markdown file containing frontmatter configuration and an instruction body.
 *   **AgentSpec**: The normalized runtime and catalog policy object derived from a recipe.
 *   **audience**: Determines visibility and routing (`base` | `shadow` | `custom` | `internal`).
-*   **source**: Origin of the recipe (`builtin` | `extension` | `user` | `project`).
+*   **source**: Origin of the recipe (`builtin` | `plugin` | `user` | `project`).
 
 ### Discovery, Overrides, and Precedence
 At startup, Clio loads recipes in four precedence tiers:
@@ -24,19 +24,19 @@ At startup, Clio loads recipes in four precedence tiers:
 | Source | Root | Notes |
 | --- | --- | --- |
 | **Built-in** | `src/domains/agents/builtins/*.md` in the installed package | Shipped defaults. |
-| **Extension** | Each enabled extension's `agents` resource root | Loaded in stable extension-source order. An extension recipe may bind only skills from the same extension. |
+| **Plugin** | Each enabled plugin's `agents` resource root | Loaded in stable plugin-source order. A plugin recipe may bind only skills from the same plugin. |
 | **User** | `<configDir>/agents/*.md` | Per-user recipes. `<configDir>` follows Clio's XDG/platform config directory. |
 | **Project** | `.clio-coder/agents/*.md` under the current repo | Repository-local overrides and additions (custom/domain agents). |
 
 Recipe IDs are derived from filenames (e.g., `architect.md` -> `architect`). Recipes must live directly under their respective directories.
 
 *   **Customization**: User-level agents can override/customize shipped base agents.
-*   **Extension Protection**: Extension recipes cannot override any shipped builtin.
+*   **Plugin Protection**: Plugin recipes cannot override any shipped builtin.
 *   **Shadow Protection**: User or project agents can **never** override shadow or internal agents.
 *   **Built-in Protection**: Project agents cannot override any shipped built-ins; they are strictly treated as custom/domain agents.
 *   **Reserved IDs**: The IDs `worker`, `delegate`, and `auto` cannot be registered outside the builtin tier.
 *   **Local Ignored Custom Examples**: Local examples (e.g., `benchmark-runner`, `clio-dev`, `implementer`, `scientific-validator`) may exist under `.clio-coder/agents` for documentation or test purposes, but are ignored if they collide with reserved/built-in rules.
-*   **Fleet Contracts**: Shipped builtin fleet contracts (`build-test`, `build-review`, `sdlc`) live under `src/domains/agents/fleets/*.md`. Enabled-extension contracts load next, user contracts at `<configDir>/fleets/<name>.md` load after them, and project contracts at `.clio-coder/fleets/<name>.md` take highest precedence. The parser accepts contract versions 1 through 5. Version 4 introduces enforced per-step `writes` boundaries; version 5 adds plan and gate steps, per-step target or profile routes, and the `writers: 1` single-writer declaration. Deterministic code steps reference commands declared in `.clio-coder/fleets/commands.yaml`.
+*   **Fleet Contracts**: Shipped builtin fleet contracts (`build-test`, `build-review`, `sdlc`) live under `src/domains/agents/fleets/*.md`. Enabled-plugin contracts load next, user contracts at `<configDir>/fleets/<name>.md` load after them, and project contracts at `.clio-coder/fleets/<name>.md` take highest precedence. The parser accepts contract versions 1 through 5. Version 4 introduces enforced per-step `writes` boundaries; version 5 adds plan and gate steps, per-step target or profile routes, and the `writers: 1` single-writer declaration. Deterministic code steps reference commands declared in `.clio-coder/fleets/commands.yaml`.
 
 ---
 
@@ -151,7 +151,7 @@ model selection belong to dispatch, not the recipe.
 
 Every recipe must declare `name`, `description`, `budget`, and every other key in the required set; no display defaults are synthesized. `budget` must be a non-null YAML object containing `toolCalls`, `readReserve`, and `synthesis`, plus an optional `maximum` ceiling object such as architect's `maximum: {toolCalls: 150, readReserve: 16}`. The numeric fields must be safe integers, `toolCalls > 0`, and `0 <= readReserve < toolCalls`; `synthesis` must be a boolean. Unknown, missing, quoted-numeric, floating-point, null, and relationally invalid values reject the recipe with its source path and property. Scout declares `18/4/true`; Coder declares `50/5/true`. The model-visible catalog shows the declared policy, never a mutable effective cap.
 
-Only shipped recipes may declare the `base`, `shadow`, or `internal` audience. Extension, user, and project recipes must declare `audience: custom`; the discovery root determines that provenance and the parser refuses a conflicting claim.
+Only shipped recipes may declare the `base`, `shadow`, or `internal` audience. Plugin, user, and project recipes must declare `audience: custom`; the discovery root determines that provenance and the parser refuses a conflicting claim.
 
 The operator cap is independent and cannot be widened by a recipe. Dispatch clamps `toolCalls` to that cap and clamps `readReserve` to zero when canonical `read` is absent after tool admission. Reserve slots admit only `read`, not every read-class tool. Blocked non-read attempts do not consume admitted reserve slots, but they still count toward the operator attempt ceiling.