@iowarp/clio-coder 0.4.6 → 0.4.8

package/docs/guide/extensions-and-sharing.md

@@ -1,11 +1,10 @@
 # Extensions, Resources, and Share Archives
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Extensions, Resources, and Share Archives visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/extensions_blueprint.html).
+Clio Coder has two package kinds. A plugin is a domain bundle: prompts, skills, agent recipes, fleet contracts, scripts, and reference files, installed with `clio-coder library install <path>`. A harness extension is executable runtime capability: command tools and hook declarations, installed with `clio-coder extensions install <path>`. Only plugins contribute resources; see [plugins.md](plugins.md) and [harness-extensions.md](harness-extensions.md) for each contract.
 
-Clio Coder has lightweight community-oriented resource packaging. Extensions are filesystem bundles that can contribute prompts, skills, agent recipes, and fleet contracts. Manifests may also reserve a theme root, but the runtime does not apply extension themes. Share archives are portable JSON files for moving project and user Clio resources between machines or collaborators.
+Share archives are portable JSON files for moving project and user Clio resources between machines or collaborators.
 
-Source of truth: `src/domains/extensions/**`, `src/domains/resources/**`, `src/domains/share/**`, `src/cli/extensions.ts`, and `src/cli/share.ts`.
+Source of truth: `src/domains/extensions/**`, `src/domains/plugins/**`, `src/domains/resources/**`, `src/domains/share/**`, `src/cli/extensions.ts`, and `src/cli/share.ts`.
 
 ---
 
@@ -17,7 +16,7 @@ Prompts and skills both add compatibility roots so that the command and skill fi
 
 | Precedence | Scope | Source | Root |
 | --- | --- | --- | --- |
-| 10 | package | extension | enabled extension resource roots |
+| 10 | package | plugin | enabled plugin resource roots |
 | 20 | user | claude / codex / opencode | `~/.claude/commands`, `~/.codex/prompts`, `~/.config/opencode/command` |
 | 30 | user | clio | `<configDir>/prompts` |
 | 40 | project | claude / codex / opencode | `.claude/commands`, `.codex/prompts`, `.opencode/command` (untrusted by default) |
@@ -27,7 +26,7 @@ The skill precedence, lowest to highest, is:
 
 | Precedence | Scope | Source | Root |
 | --- | --- | --- | --- |
-| 10 | package | extension | enabled extension resource roots |
+| 10 | package | plugin | enabled plugin resource roots |
 | 20 | user | agents / claude / codex / copilot / opencode | `~/.agents/skills`, `~/.claude/skills`, `~/.codex/skills`, `~/.copilot/skills`, `~/.config/opencode/skills` |
 | 30 | user | clio | `<configDir>/skills` |
 | 40 | project | agents / claude / codex / copilot / opencode | `.agents/skills`, `.claude/skills`, `.codex/skills`, `.github/skills`, `.opencode/skills` (untrusted by default) |
@@ -36,11 +35,21 @@ The skill precedence, lowest to highest, is:
 
 Clio-native roots intentionally outrank shared compatibility roots at the same scope, so `.clio-coder/skills` overrides a project `.codex/skills` skill of the same name, and `<configDir>/skills` overrides `~/.agents/skills`. If multiple compatibility roots contain the same name at the same precedence, the tie breaks by the registry's agent order rather than by path spelling, so a skill symlinked into two foreign roots resolves to the same winner on every machine. If two roots resolve to the same canonical `SKILL.md` through a symlink, Clio keeps the higher-precedence entry and records a diagnostic naming the path that is in use.
 
+### Native skills, foreign compatibility roots, and collision resolution
+
+When inspecting skills discovered across native and foreign compatibility roots, candidate resolution follows strict, source-grounded precedence and trust rules implemented in `src/domains/resources/skills/loader.ts`:
+
+1. **Trust-first collision resolution**: `compareSkillCandidates` compares **trusted status first** (`Number(a.trusted) - Number(b.trusted)`), then precedence level, then registry agent order (`interopSourceRank`), and finally file path. This ordering governs both canonical-file deduplication (`dedupeCanonicalSkillPaths`) and same-name collision resolution (`resolveSkillCollisions`). Crucially, trust-first ordering prevents an untrusted project compatibility copy (such as an unvetted `.claude/skills/my-skill` or `.agents/skills/my-skill`) from winning a collision against an admitted native library skill and then disappearing at model visibility time. The trusted native skill wins and remains active.
+2. **Canonical file deduplication**: If multiple scanned roots resolve to the exact same canonical `SKILL.md` path on disk (via symlinks), `dedupeCanonicalSkillPaths` sorts candidates with `compareSkillCandidates` and retains only the winning candidate, logging a diagnostic for the shadowed path.
+3. **Model visibility**: Only admitted skills passing `modelVisibleSkills` (`skill.trusted && !skill.disableModelInvocation`) are visible in `context(scope="skills")` or eligible for model invocation. Setting `disable-model-invocation: true` in skill YAML frontmatter keeps the skill in the catalog for manual operator slash command usage while withholding it from model context.
+4. **Foreign package trust vs unmanaged roots**: Foreign installed packages (carrying `origin: "import"` or `"interop"` and `trust: "foreign"`) are not automatically admitted just because they are installed at user scope. In `defaultSkillRoots`, plugin roots receive `trusted: root.trust !== "foreign" || trustProjectCompatRoots` regardless of install scope; the `integrations.projectResources.trustProjectImports` (`skills.trustProjectCompatRoots`) setting serves as the explicit trust gate for foreign package skills. Conversely, unmanaged user-scoped compatibility roots (`~/.claude/skills`, `~/.agents/skills`, `~/.codex/skills`) have native user trust, while unmanaged project-scoped compatibility roots (`.claude/skills`, `.agents/skills`) remain untrusted until that setting is enabled.
+5. **Project-package shadowing**: Shadowing and disabling of entire packages operates through the managed package lifecycle (`state.json`), where a project-scoped package installation can shadow and disable an underlying user-scoped package of the same ID, rather than through an arbitrary filesystem switch on unmanaged files.
+
 ---
 
 ## Prompt templates
 
-Prompt templates are Markdown files under a prompt root. Filename is the command name.
+Prompt templates are Markdown files under a prompt root. Filename is the command name. Every loaded template, including a plugin's namespaced `/<plugin>:<name>` prompts, is offered in the composer's slash autocomplete after the built-in commands, with its `description` and `argument-hint`; an unavailable template is listed disabled with its reason.
 
 Example `.clio-coder/prompts/bugfix.md`:
 
@@ -61,18 +70,38 @@ Return:
 Use in the TUI:
 
 ```text
-/resources prompts
+/prompts
 /bugfix src/parser.ts empty input crashes
 ```
 
 Templates without frontmatter are accepted; Clio derives a fallback description from the first non-empty line. Invalid frontmatter degrades to a warning for prompt templates rather than failing the whole load.
 
+### Display-only templates
+
+A template whose body is written for the operator rather than the model, such as a package's `help` reference, declares `display-only: true` in its frontmatter:
+
+```md
+---
+description: Overview of the package commands
+display-only: true
+---
+
+Display the following:
+
+```text
+ /pkg:help      This reference
+ /pkg:status    Project dashboard
+```
+```
+
+Submitting `/pkg:help` renders the template locally as an operator card in the transcript, headed by the command name and its source package. Nothing is sent to the model, nothing is recorded in the model-facing session context, and no tokens are spent. The card shows the first fenced code block when the body has one, otherwise the whole body, wrapped to the terminal width with no truncation and scrollable like any other transcript output. Arguments after the command name are ignored. The composer's autocomplete lists such a template with a `reference` marker, and `/prompts` marks it the same way. Headless `clio-coder run /pkg:help` prints the same text to stdout and exits 0 without booting a provider or a session.
+
 ### Foreign prompt roots
 
 A Claude Code slash command in `.claude/commands`, a Codex prompt in `.codex/prompts`, and an OpenCode command in `.opencode/command` are prompt templates Clio reads directly, at both user and project scope. A foreign prompt is text substituted into a message the operator typed, so it keeps the untrusted-by-project default that skills have and never gains an execution grant of its own.
 
 User-scope foreign prompts are trusted because they came from the operator's
-machine. A project-scope prompt lists in `/resources prompts` with an
+machine. A project-scope prompt lists in `/prompts` with an
 `untrusted` marker and refuses substitution until
 `integrations.projectResources.trustProjectImports: true` opts in. An untrusted
 template sends nothing to the model. A token naming neither a command nor a
@@ -110,7 +139,7 @@ Use in the TUI:
 /skill hdf5-review review the output validation path
 ```
 
-`/skill` opens the Skills Hub with discovered project skills, user skills, and marketplace entries. `/skill <name> [args]` submits `args` with a pending skill request; the model must call `context` (scope="skills") for that skill before following the workflow. The same pending-request path runs in headless mode, so `clio-coder run "/skill hdf5-review inspect the writer"` matches the interactive behavior.
+`/skill` opens the library overlay (`/library skill`) with discovered project skills, user skills, and marketplace entries. `/skill <name> [args]` submits `args` with a pending skill request; the model must call `context` (scope="skills") for that skill before following the workflow. The same pending-request path runs in headless mode, so `clio-coder run "/skill hdf5-review inspect the writer"` matches the interactive behavior.
 
 Every activation records a session ledger entry with the skill name, file path, hash, source, trigger (`slash-command` or `tool`), and turn id when one is available. The same ledger is mirrored into session metadata, prompt diagnostics, and run receipts. Compaction keeps the newest active skill turn in the retained suffix so a loaded skill is not silently summarized away.
 
@@ -132,26 +161,27 @@ Shared user roots are model-visible by default, like the Clio user root. Project
 
 Opt in to model-visible project compatibility roots by setting `integrations.projectResources.trustProjectImports: true` in `settings.yaml`. `.clio-coder/skills` is always trusted as the Clio-native project root.
 
-### Loading with context, writing directly
+### Loading with context and skill authoring
 
 `context(scope="skills")` lists model-visible skills when called with no `name`, or loads a pending skill body by `name`. It returns structured metadata (`name`, `description`, `path`, `base_dir`, `hash`, `source`, `scope`, `disable_model_invocation`, parsed tool policy fields, diagnostics, and frontmatter metadata) plus the body. Pass `include_tree: true` to list sibling files under the skill base directory, capped internally at 50 entries. The skills scope never executes bundled scripts and only resolves skills the model is allowed to see.
 
-Creating a skill is writing a `SKILL.md` file with the ordinary write tool: `.clio-coder/skills/<name>/SKILL.md` for project scope, or the Clio config skills directory for user scope. The loader validates frontmatter on load (`clio-coder skills validate` reports diagnostics), and the `skill-craft` shipped skill documents the frontmatter contract and craft rules.
+Creation under protected roots is operator authority: the ordinary model `write` and `edit` tools cannot write protected active skill roots (`.clio-coder/skills/<name>/` or the user `<configDir>/skills/`). Model-authored skills must be created outside protected roots (for example in a staging workspace or package directory) and then installed by the operator with `clio-coder library install <path> [--user|--project]`, or copied directly into an active root by the operator. The loader validates frontmatter on demand (`clio-coder library validate <package-path|SKILL.md>` reports diagnostics), and the `skill-craft` shipped skill documents the frontmatter contract and craft rules.
 
-### Skills CLI
+### Library and skill commands
 
 ```bash
-clio-coder skills list [--json] [--all]
-clio-coder skills search <query> [--json]
-clio-coder skills inspect <name> [--json]
-clio-coder skills validate [path] [--json]
-clio-coder skills install <name|path|github-url> [--user|--project] [--name <name>] [--force]
-clio-coder skills update <name> | --all [--force]
-clio-coder skills sync [--force]
-clio-coder skills eval <name|path> [--scenario <id>] [--target <id>] [--workspace <path>] [--timeout <seconds>] [--trust-fixtures] [--allow-network] [--json]
+clio-coder library list [--kind skill] [--user|--project] [--json]
+clio-coder library search [query] [--kind skill] [--json]
+clio-coder library inspect <path|kind:name|name> [--user|--project] [--json]
+clio-coder library validate <package-path|SKILL.md> [--json]
+clio-coder library install <path|kind:name|name> [--user|--project] [--force] [--with-requirements] [--dry-run] [--json]
+clio-coder library update <kind:name|name> [--user|--project] [--force] [--json]
+clio-coder library sync
+clio-coder library skills [--all] [--json]
+clio-coder eval skill <name|path> [--scenario <id>] [--target <id>] [--workspace <path>] [--timeout <seconds>] [--trust-fixtures] [--allow-network] [--json]
 ```
 
-`eval` (experimental) executes a skill's `evals.md` RED-GREEN scenarios with
+`eval skill` (experimental) executes a skill's `evals.md` RED-GREEN scenarios with
 baseline, treatment, and judge runs; see
 [skills-marketplace.md](skills-marketplace.md) for the catalog contract it
 verifies. Fixture commands in an `evals.md` are real shell and only run with
@@ -172,7 +202,7 @@ Clio is local-first. Skills run from disk and no chat turn depends on network ac
 npx skills add <skill> -a codex   # installs into ~/.codex/skills
 ```
 
-Clio does not call Skills.sh during startup or prompt assembly, and does not emit its own telemetry. If you run `npx skills`, its telemetry follows that CLI and can be disabled with `DISABLE_TELEMETRY=1`. Skills.sh remote search and audit are not enabled in this release. Clio does support local marketplace search plus `clio-coder skills install <name|path|github-url>`: bare names resolve through the local marketplace, and explicit local paths or GitHub URLs install directly.
+Clio does not call Skills.sh during startup or prompt assembly, and does not emit its own telemetry. If you run `npx skills`, its telemetry follows that CLI and can be disabled with `DISABLE_TELEMETRY=1`. Skills.sh remote search and audit are not enabled in this release. Clio supports library package discovery and installation via `clio-coder library install <path|kind:name|name> [--user|--project]`: bare names and `kind:name` references resolve through the library catalog, and local paths require a valid package containing a root `plugin.json`. Raw or unindexed GitHub URLs cannot be installed directly; remote package installation requires a catalog entry with version and full-tree SHA-256 pin.
 
 ### Prompt envelope and safety
 
@@ -185,35 +215,42 @@ Skill bodies never enter the prompt uninvited. The model discovers skills only t
 An extension root contains `clio-coder-extension.yaml`, `clio-coder-extension.yml`, or `clio-coder-extension.json`.
 
 ```yaml
-manifestVersion: 1
-id: lab-pack
-name: Lab Pack
+id: lab-tools
+name: Lab Tools
 version: 1.0.0
-description: Prompts and skills for this lab
-resources:
-  prompts: prompts
-  skills: skills
-  agents: agents
-  fleets: fleets
-  themes: themes
+description: Executable capabilities for this lab
 compatibility:
-  clio: ">=0.2.0"
+  clio: ">=0.4.7"
+capabilities:
+  tools:
+    - name: summarize
+      description: Return the count and sum of supplied measurements.
+      runtime: node
+      entrypoint: tools/summarize.cjs
+      inputSchema:
+        type: object
+        properties:
+          values: { type: array, items: { type: number } }
+        required: [values]
+        additionalProperties: false
 ```
 
-Required fields are `manifestVersion: 1`, `id`, `version`, and `description`. `name` defaults to `id` when absent, and `resources` is optional. When `resources` is present it must be an object containing only `prompts`, `skills`, `agents`, `fleets`, and `themes`, each with a non-empty relative directory path. Clio consumes prompt, skill, agent, and fleet roots. A manifest may reserve a `themes` path for forward compatibility, but Clio does not apply theme resources.
+Required fields are `id`, `version`, and `description`. `name` defaults to `id` when absent. `capabilities` is optional, so a package whose only contribution is a root `hooks.yaml` is valid. The command-tool contract lives in [harness-extensions.md](harness-extensions.md).
+
+A manifest that declares `resources`, `prompts`, `skills`, `agents`, `fleets`, or `themes` is invalid. Those are plugin content, and the diagnostic says so: install the bundle with `clio-coder library install <path>` instead.
 
 IDs must be lowercase and may include numbers, dots, underscores, and hyphens; they must start/end alphanumeric.
 
-`compatibility.clio` is optional. When present, it must be a valid SemVer range such as `>=0.3.8`, `^0.3.8`, or `0.3.x`. Installation refuses a package whose range excludes the running Clio version and names the extension, its declared range, and that running version. Clio repeats the check whenever it loads installed extensions, so a package that becomes incompatible after a Clio version change stays visible in `extensions list` with its diagnostic but contributes no resources. An incompatible project package does not hide a compatible user package with the same ID. A manifest without `compatibility.clio` keeps the existing unrestricted behavior.
+`compatibility.clio` is optional. When present, it must be a valid SemVer range such as `>=0.3.8`, `^0.3.8`, or `0.3.x`. Installation refuses a package whose range excludes the running Clio version and names the extension, its declared range, and that running version. Clio repeats the check whenever it loads installed extensions, so a package that becomes incompatible after a Clio version change stays visible in `extensions list` with its diagnostic but contributes no command tools or hooks. An incompatible project package does not hide a compatible user package with the same ID. A manifest without `compatibility.clio` keeps the existing unrestricted behavior.
 
-### Extensions that dispatch
+### Callers that dispatch
 
-An extension that builds a `DispatchRequest` against the `DispatchContract` is a
+A caller that builds a `DispatchRequest` against the `DispatchContract` is a
 dispatch producer and is bound by the typed-intent compatibility rules like any
 other. Build the declaration with `declaredScopeIntent()` from the dispatch
 domain rather than assembling the normalized object by hand: it runs the same
 path grammar, caps, deduplication, and provenance construction the dispatch tool
-uses, so an extension cannot mint an intent shape the tool could not.
+uses, so a caller cannot mint an intent shape the tool could not.
 
 ```ts
 import { declaredScopeIntent } from "../domains/dispatch/index.js";
@@ -223,11 +260,11 @@ if (!built.ok) throw new Error(`${built.reason}: ${built.message}`);
 await dispatch.dispatch({ agentId: "coder", executionRole: "builder", task, intent: built.intent });
 ```
 
-An extension that declares nothing keeps working: scope falls back to legacy
-inference over its task and briefing text, and the request is refused only when
-it states a contradiction, such as a legacy `writeRoots` disagreeing with a
-declared `write_roots`. Declaring is what stops an applicable project rule from
-being missed because the task text happened not to spell a path. See
+A caller that declares nothing keeps working: scope falls back to inference over
+its task and briefing text, and the request is refused only when it states a
+contradiction, such as an inferred `writeRoots` disagreeing with a declared
+`write_roots`. Declaring is what stops an applicable project rule from being
+missed because the task text happened not to spell a path. See
 [dispatch-typed-intent.md](../architecture/dispatch-typed-intent.md).
 
 ---
@@ -252,27 +289,27 @@ Install locations:
 
 Project extensions shadow user extensions with the same ID. Use `--all` to list shadowed/disabled entries.
 
-Installed packages are admitted only when their current tree matches the SHA-256 digest in `extensions/state.json`. `clio-coder upgrade` adds digests to pre-digest v1 install records after validating and hashing each installed tree, preserves `disabled`, `source`, and `installedAt`, and backs up the original state before the atomic rewrite. Invalid or changing trees are not blessed: they stay visible and inactive with reinstall guidance. Listing extensions, booting Clio, inspection, and plain doctor runs never perform this migration.
+Installed packages are admitted only when their current tree matches the SHA-256 digest in `extensions/state.json`. An install record without a digest, a drifted tree, and a corrupt state file all fail closed: the package stays visible and inactive, and its diagnostic says to reinstall with `--force`. Listing extensions, booting Clio, inspection, and plain doctor runs never rewrite install state.
 
 ### Generations and reload
 
-A running session does not read installed packages on every resource load. While domains start, the extensions domain publishes nothing: readers use an ephemeral generation-0 projection. The composition root then asks the extensions domain to build an immutable candidate for the session's working directory and builds the matching user-hook registration table from it. After validating that both candidates are still current, the composition root publishes the snapshot and hooks with two adjacent reference assignments. That paired boot snapshot is generation 1. It contains package identity and provenance, the resolved skill, prompt, agent, fleet, and theme roots of each loadable package, and the parsed `hooks.yaml` declarations captured from the exact bytes the install digest covered. Every consumer in the process then reads the committed generation, so consecutive loads within one turn agree on the package set.
+A running session does not read installed packages on every load. While domains start, the extensions domain publishes nothing: readers use an ephemeral generation-0 projection. The composition root then asks the extensions domain to build an immutable candidate for the session's working directory and builds the matching user-hook registration table from it. After validating that both candidates are still current, the composition root publishes the snapshot and hooks with two adjacent reference assignments. That paired boot snapshot is generation 1. It contains package identity and provenance, the command-tool declarations of each loadable package, and the parsed `hooks.yaml` declarations captured from the exact bytes the install digest covered. Every consumer in the process then reads the committed generation, so consecutive loads within one turn agree on the package set.
 
-`/resources extensions reload` is the only in-session way to publish a later generation. It rebuilds the snapshot from disk, re-verifies every installed tree against `state.json`, builds the user-hook registrations for the candidate, validates both candidates, and then performs the same two adjacent assignment-only publications. No callback, event, log, or refusal sits between them; conflict diagnostics and the `extensions.reloaded` event run only after both references are live. Observers therefore see the previous resources with the previous hooks or the new ones with the new ones, never an intermediate pairing. The command reports the new generation, which packages were added, removed, or modified, and how many hooks were registered, dropped, or rejected. A tree that no longer verifies is listed as inactive and contributes nothing until it is reinstalled. A build failure or stale candidate publishes neither side and reports why.
+`/extensions reload` is the only in-session way to publish a later generation. It rebuilds the snapshot from disk, re-verifies every installed tree against `state.json`, builds the user-hook registrations for the candidate, validates both candidates, and then performs the same two adjacent assignment-only publications. No callback, event, log, or refusal sits between them; conflict diagnostics and the `extensions.reloaded` event run only after both references are live. Observers therefore see the previous hooks or the new ones, never an intermediate pairing. The command reports the new generation, which packages were added, removed, or modified, and how many hooks were registered, dropped, or rejected. A tree that no longer verifies is listed as inactive and contributes nothing until it is reinstalled. A build failure or stale candidate publishes neither side and reports why.
 
-Reloading an unchanged tree still publishes a new generation with the same content digest; content identity is the digest, not the generation number. Installs, enables, disables, and removes performed by `clio-coder extensions` in another process are invisible to a running session until the operator reloads or restarts. There is no filesystem watcher, so a CLI mutation never becomes an implicit mid-turn hook change. Resource files themselves (skill and prompt bodies, agent and fleet recipes) are still read at use time; a package mutated on disk after its generation was built can serve changed files until the next reload detects the drift and deactivates it.
+Reloading an unchanged tree still publishes a new generation with the same content digest; content identity is the digest, not the generation number. Installs, enables, disables, and removes performed by `clio-coder extensions` in another process are invisible to a running session until the operator reloads or restarts. There is no filesystem watcher, so a CLI mutation never becomes an implicit mid-turn hook change. Command-tool schemas are frozen when a session registry is created, so a reload never changes a live model's tool surface; restart the session for that. Plugin resources have their own generation and their own `/library reload`.
 
 If extension state is corrupt, loading remains fail-closed. A normal reinstall refuses it; `extensions install <valid-source> --force` backs up the corrupt state and parks the previous package bytes before installing and recording the verified replacement. `extensions remove <id>` can also remove an unverifiable package from the load path while preserving both its bytes and any corrupt state in the paths printed by the command. These recovery backups are deliberately not treated as installed packages.
 
 ### Skill pack distribution
 
-Clio Coder should not grow built-in skills in the harness. Distribute reusable Clio skills as extension packages instead. A future `iowarp/clio-kit` bundle can carry `clio-coder-extension.yaml` plus a `skills/` directory, and users can install it with `clio-coder extensions install <path> --user` or `--project`.
+Reusable skill packs belong in the Library. Clio-Coder currently bundles its canonical recipes under this repository's `library/`; no separate `iowarp/clio-kit` marketplace is required. A shareable skill pack carries a root `plugin.json` plus a `skills/` directory, and users install it with `clio-coder library install <path> --project` or without the flag for user scope. Harness tools, hooks, commands, and UI belong in the separate extension system.
 
 Recommended layout:
 
 ```text
-clio-kit/
-  clio-coder-extension.yaml
+lab-skills/
+  plugin.json
   skills/
     hpc-review/
       SKILL.md
@@ -282,7 +319,7 @@ clio-kit/
       SKILL.md
 ```
 
-This keeps the runtime local-first and small. Clio Coder discovers enabled extension skill roots, records provenance as `source: extension`, and still requires normal tool safety gates for any script a skill asks the agent to run.
+This keeps the runtime local-first and small. Clio Coder discovers enabled plugin skill roots, records provenance as `source: plugin`, and still requires normal tool safety gates for any script a skill asks the agent to run.
 
 ---
 
@@ -327,7 +364,7 @@ Options:
 | `--prompts` | Include prompt templates. |
 | `--skills` | Include skills. |
 | `--settings` | Include non-secret settings fragment. |
-| `--extensions` | Include extension bundle files, excluding extension `state.json`. |
+| `--extensions` | Include harness extension bundle files, excluding extension `state.json`. |
 | `--agents` | Include agent recipe files. |
 | `--fleets` | Include fleet contract files. |
 | `--all` | Include every supported resource class. |
@@ -364,7 +401,7 @@ clio-coder import project.clio-coder-share.json --dry-run
 
 ## Community packaging guidance
 
-- Keep extension packages small and reviewable.
+- Keep plugin and extension packages small and reviewable.
 - Treat prompts and skills as source code: document assumptions, expected evidence, and validation commands.
-- Do not put secrets in extension packages or share archives.
+- Do not put secrets in packages or share archives.
 - Prefer project-scoped resources for repository-specific instructions and user-scoped resources for personal workflow helpers.

package/docs/guide/fleet-dispatch.md

@@ -1,8 +1,5 @@
 # Fleet Dispatch
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Fleet Dispatch visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/fleet_dispatch_blueprint.html).
-
 Clio Coder dispatches bounded worker agents. With a fleet configured, those
 workers run on remote machines over SSH while the orchestrator keeps every
 guarantee it makes locally: one admission path, one autonomy matrix, one
@@ -254,7 +251,7 @@ runs never acquire it.
 
 A singular writer or an item in `tasks` may declare `worktree: true` and
 `apply: "merge" | "preserve"`. The default is `merge`. Clio creates
-`.clio-coder/worktrees/<runId>/` on `clio/task/<runId>`, maps the worker cwd and
+`.clio-coder/worktrees/<runId>/` on `clio-coder/task/<runId>`, maps the worker cwd and
 protected artifacts into that checkout, and runs declared host verification
 there. The approved execution snapshot renders both fields and freezes the
 parent checkout as the merge destination.
@@ -368,7 +365,7 @@ and covered by receipt integrity.
 
 `detach: true` validates, admits, and spawns every task, then returns. The
 reported id is the logical assignment id (also the first attempt's run id).
-For an in-flight attached dispatch, pressing `Alt+S` or `Ctrl+Alt+B` converts
+For an in-flight attached dispatch, using `Ctrl+G`, then `s`, or `/background` converts
 the running attached dispatch into a detached batch. Backgrounding checks
 against a refusal table: it refuses Scout dependency plans driving stages from
 the turn, compete judge gates, review cycle gates, multi-step pipelines,
@@ -414,7 +411,7 @@ and surfaces as an explicit operator decision, never a silent failure.
 
 N candidate builders (2 to 4) run the same task, each in its own scratch git
 worktree under `.clio-coder/worktrees/<group>/` on its own
-`clio/compete/<group>/<n>` branch. Each candidate's work is committed on its
+`clio-coder/compete/<group>/<n>` branch. Each candidate's work is committed on its
 branch; a read-only judge ranks the branches and names a winner
 (`WINNER: <n>`). At full-auto the winning branch is merged. At supervised
 levels the winner's branch and worktree are preserved and the operator
@@ -614,6 +611,7 @@ commands:
 
 Each command entry supports:
 - `argv` (required): Array of command arguments starting with the binary name (no shell strings).
+- `argumentSlots` (optional): Operator-declared positional data slots, each with a unique `name` and required `maxLength` (1 to 8192). At most 64 slots. Omission forbids appended fleet arguments; declared slots are all required.
 - `cwd` (optional): Repository-relative working directory (defaults to repository root).
 - `timeoutMs` (optional): Per-step execution timeout in milliseconds (defaults to 600,000 ms; bounds: 1,000 to 3,600,000 ms).
 - `env` (optional): Array of extra environment variable names to pass through on top of `FLEET_COMMAND_BASE_ENV` (`PATH`, `HOME`, `LANG`, `LC_ALL`, `TZ`, `TMPDIR`).
@@ -622,6 +620,32 @@ Each command entry supports:
 The whole-token `{{commitMessage}}` substitution is available to commit steps. The whole-token `{{path}}` substitution is available to version 5 gate commands. Each substitution becomes exactly one argv element and never passes through a shell.
 
 
+A fleet may supply per-task data only when the operator explicitly declares slots in the repository registry. Keep the executable, script path, and fixed flags in `argv`; the fleet cannot replace them. Use a fixed `--` separator where the registered program supports it. For example:
+
+```yaml
+# .clio-coder/fleets/commands.yaml, owned by the operator
+version: 1
+commands:
+  check-materials-task:
+    argv: ["python3", "scripts/check_materials_task.py"]
+    argumentSlots:
+      - name: taskDirectory
+        maxLength: 256
+```
+
+```yaml
+# One code step in a version 2 or newer fleet
+kind: code
+id: check-task
+command: check-materials-task
+args: ["{{taskDir}}"]
+scope: readonly
+dependencies: []
+```
+
+Run with `--var taskDir=.research/tasks/task-01`. A slot receives exactly one literal argument. Values must be nonempty, fit the slot's length limit, contain no NUL, and not start with `-`; fixed flags belong in the operator's registry. A whole-token `{{variable}}` binds before admission and participates in the plan hash. Missing variables, undeclared or excess slots, embedded placeholders, and flag-like values fail before execution. The code runner repeats slot validation for direct or in-memory plans. Spaces and shell metacharacters remain data without another expansion pass. Existing fixed commands accept no extra args.
+
+
 ## Measured route selection and agent automation
 
 The joint resolver treats agent, target, model, runtime, and node as one
@@ -868,7 +892,7 @@ hard block.
   stays compact, so a fan-out of scouts costs one card each until an operator
   opens one. Detail follows the cursor rather than pinning to a run.
 - The board and the transcript worker block read one projection
-  (`src/interactive/worker-progress.ts`), so they cannot disagree about what a
+  (`src/domains/observability/worker-progress.ts`), so they cannot disagree about what a
   worker is saying or touching. It keeps 40 lines and 4096 bytes of tail, 8
   distinct tool names, 4 recent actions, and accepts 16 KB of delta bytes per
   250 ms; what the bounds refuse is counted and named on the card beside the

package/docs/guide/glossary.md

@@ -1,8 +1,5 @@
 # Clio Coder Glossary
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio Coder Glossary visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/glossary_blueprint.html).
-
 This document defines the 50 core architectural concepts and terminology used throughout Clio Coder, mapped to their authoritative TypeScript type definitions in `src/`.
 
 ---
@@ -94,7 +91,7 @@ This document defines the 50 core architectural concepts and terminology used th
 - **Owning Type**: `WorkerEntryRenderOptions` in `src/interactive/renderers/worker-entry.ts`.
 
 ### 22. Interop
-- **Definition**: The domain governing discovery, compatibility roots, and delegation wiring for other coding agents installed on the local machine and in the repository.
+- **Definition**: Read-only discovery of coding agents, their user and project resources, and connection state. The operator can approve adoption of safe text resources into the library; foreign provenance and the project-import trust gate persist. See [Coding agent interoperability](interop.md).
 - **Owning Type**: `InteropContract` in `src/domains/interop/contract.ts`.
 
 ### 23. Consent Record