@iowarp/clio-coder 0.4.5 → 0.4.7

package/docs/guide/interop.md

@@ -0,0 +1,243 @@
+# Coding agent interoperability
+
+> **Visual blueprint:** See the [visual reference](../html/interop_blueprint.html) in the source checkout.
+
+Interoperability runs both ways. Inbound, Clio can discover resources held by
+Claude Code, Codex, Antigravity CLI, GitHub Copilot CLI, and OpenCode, then adopt
+safe text resources into the library after approval. Outbound, the same canonical
+`library/` sources this repository ships are installable by Claude Code and
+loadable by Codex without a converted copy. Inspection and adoption use zero
+model tokens. Gemini, Cursor, and the shared Agent Skills convention retain their
+existing presence detection; this inventory does not extend their capabilities.
+
+## Outbound: Use this library from Claude Code
+
+The repository is a standard Claude Code marketplace. `.claude-plugin/marketplace.json`
+is generated by `pnpm run library:pin` from the pinned packages in
+`library/registry.yaml`, so it cannot describe a package the repository does not
+actually contain.
+
+```bash
+claude plugin marketplace add iowarp/clio-coder
+claude plugin install tdd@clio-coder
+claude plugin install materio@clio-coder
+```
+
+A local checkout or the installed npm package works the same way, because every
+entry's source is a relative path inside the repository:
+
+```bash
+claude plugin marketplace add ./path/to/clio-coder
+claude plugin marketplace add "$(npm root -g)/@iowarp/clio-coder"
+```
+
+The marketplace publishes 34 entries: the 33 curated skill packages and the
+`materio` bundle. What each entry becomes on the Claude Code side:
+
+| Source layout | What Claude Code loads |
+| --- | --- |
+| `library/skills/<category>/<name>/` with a root `SKILL.md` | One skill, named by the `SKILL.md` frontmatter, with its `references/` companions |
+| `library/plugins/materio/` with a `skills/` directory | Materio's six portable skills and nothing else |
+
+Nothing is converted and no recipe body is duplicated. The packages carry their
+portable Agent Plugins `plugin.json`, which Claude Code does not read; the
+marketplace entry supplies the name, description, version, category and license
+it shows. `claude plugin validate . --strict` passes on the generated file, so no
+entry needs `strict: false` and no package needs a second `.claude-plugin/plugin.json`.
+
+Materio's Clio-native agents, prompts and fleets sit at declared resource paths
+that no peer host scans. They travel with the installed bytes and are never
+presented as Claude-native components. `claude plugin details materio` reports
+`Skills (6)` and `Agents (0)`.
+
+### Not every library package is published
+
+A library package is published only when a host would load a real skill surface
+from it, and only when it carries nothing that host default-scans into a native
+component. Claude Code scans a plugin root for `agents/`, `commands/`, `hooks/`,
+`output-styles/` and `.mcp.json` without being asked, so a package that keeps
+Clio agent recipes in a top-level `agents/` directory would have them shown as
+native Claude agents. That is a compatibility claim nobody measured, so the
+generator leaves the package out and `pnpm run library:pin` prints the reason.
+
+Those packages remain valid first-class library packages, and agent-, prompt- and
+fleet-only packages are normal contributions. They simply have no peer-host
+projection. An author who wants one package to serve both audiences declares its
+Clio resource roots at paths no host scans, for example `"agents": "native/agents"`,
+and keeps a `skills/` directory or root `SKILL.md` for the portable surface.
+
+## Outbound: Use this library from Codex
+
+Codex scans `.agents/skills` at the repository root, in the working directory and
+in `$HOME`, recurses into subdirectories, and follows symlinks. The repository's
+own `.agents/skills` links straight at the canonical trees:
+
+```text
+.agents/skills/clio-coder  -> ../../library/skills
+.agents/skills/materio     -> ../../library/plugins/materio/skills
+```
+
+A Codex session started anywhere in a clone therefore sees all 33 curated skills
+and Materio's 6 portable skills under their canonical names, with no install step
+and no copied `SKILL.md`. To get the same catalog in every repository, link the
+canonical directories into your user skills root:
+
+```bash
+mkdir -p ~/.agents/skills
+ln -s /path/to/clio-coder/library/skills ~/.agents/skills/clio-coder
+ln -s /path/to/clio-coder/library/plugins/materio/skills ~/.agents/skills/materio
+```
+
+The clone convenience requires Git to materialize symbolic links. On Windows,
+enable Git symlink support (`core.symlinks=true`) with the required OS permission,
+or install individual skills using the following route.
+
+To install individual skills instead, use Codex's own installer, which accepts a
+GitHub repository path:
+
+```text
+$skill-installer install tdd from iowarp/clio-coder/library/skills/coding/tdd
+```
+
+Disable one without deleting it through `[[skills.config]]` in `~/.codex/config.toml`.
+
+There is deliberately no Codex plugin marketplace here. Portable Codex plugins
+discover only a root `skills/` directory, the standalone packages carry a root
+`SKILL.md`, and a `.codex-plugin` overlay cannot override that while the portable
+root `plugin.json` is present. Publishing one would claim a compatibility that
+does not exist.
+
+## Inspect installed hosts
+
+```bash
+clio-coder interop inspect
+clio-coder interop inspect --json
+```
+
+Inspection reports binary presence, a bounded version probe (or unknown),
+connection and ACP adapter state, and resource counts derived from the disk
+inventory. User and current-project resources are distinguished. JSON omits
+native source paths and declaration values, including MCP credentials.
+A cache directory establishes available content; installation and activation
+remain unknown unless a host's installation registry establishes them.
+Malformed, unreadable, symbolic-link, oversized, or unsupported configurations
+produce an unknown inventory diagnostic instead of an invented zero.
+
+The scanner reads these configuration layouts, honoring the named host home
+variable when present. An explicit fixture home ignores process host overrides.
+It never traverses session history or starts a conversational agent.
+
+| Host | User root | Project roots | Inventory and evidence commands |
+| --- | --- | --- | --- |
+| Claude Code | `~/.claude` (`CLAUDE_CONFIG_DIR`) | `.claude` | Skills, agents, commands, output styles, hooks, MCP (including `~/.claude.json` and project-root `.mcp.json`); installed plugin paths, versions and marketplace from `plugins/installed_plugins.json`. Evidence: `claude --version`, `claude plugin list --json`. |
+| Codex | `~/.codex` (`CODEX_HOME`), shared `~/.agents` | `.codex`, `.agents` | Skills, TOML agents, legacy prompts, hooks, MCP, plugin cache and plugin configuration. Evidence: `codex --version`, `codex plugin list --json`. |
+| Antigravity CLI | `~/.gemini/config` (`ANTIGRAVITY_HOME`) | `.agents` | Skills, agents, commands, plugins, import manifest, hooks, MCP. Evidence: `agy --version`, `agy plugin list`. Imported commands may already be converted into skills. |
+| GitHub Copilot CLI | `~/.copilot` (`COPILOT_HOME`) | `.github`, `.copilot` | Skills, agents, commands, hooks, MCP, plugin directories and local directory marketplaces in `settings.json`. Remote marketplace source paths remain unknown when no local installation is found. Evidence: `copilot --help`, `copilot plugin --help`, `copilot plugin list`. |
+| OpenCode | `~/.config/opencode` (`OPENCODE_CONFIG_DIR`, or `XDG_CONFIG_HOME/opencode`) | `.opencode` | Skills, singular/plural agent and command directories, MCP declarations and `opencode.json` at the project root, JavaScript/TypeScript plugins and tools. Evidence: `opencode --version`, `opencode agent list`. JSONC that cannot be parsed as JSON is reported unknown. |
+
+The listing commands above were checked in disposable profiles; runtime inspection
+uses the disk inventory and bounded version probes in disposable profiles, so
+CLI alias or log side effects cannot change the operator's home or project. Listing status itself remains
+unknown. In particular, Clio does not invoke OpenCode's agent listing against an
+operator profile because host startup can import executable modules.
+
+## Inbound: Review and adopt foreign resources
+
+### Reviewing foreign plugin source, trust, and unsupported components
+
+```bash
+clio-coder interop adopt claude-code --dry-run
+clio-coder interop adopt codex --kind skill --project
+clio-coder interop adopt claude-code --kind plugin --user --yes
+clio-coder interop adopt copilot --kind prompt --user
+```
+
+The host names are `claude-code`, `codex`, `antigravity`, `copilot`, and
+`opencode`; `claude` and `agy` are accepted aliases. `--kind` selects `skill`,
+`agent`, `prompt`, or `plugin`. The destination defaults to user scope;
+`--project` chooses the current project's library. Destination scope does not
+filter source scope: every matching discovered user and project resource is
+reviewed in the plan.
+
+The plan lists each source, destination, digest, and reason for installing or
+skipping it. Its SHA-256 identifies the reviewed projection; the library engine
+also records its standard full-tree integrity pin when publishing the package. `--dry-run` prints the plan and writes nothing. Otherwise Clio asks
+for approval in a terminal. Without a terminal, the plan remains unexecuted
+unless `--yes` was supplied. Declining installs nothing. Installation rechecks
+the source against the reviewed content; a changed source requires a new plan.
+Each package publishes atomically through the library engine; a multi-package
+plan may report successful packages alongside failures.
+
+| Resource | Adoption behavior |
+| --- | --- |
+| Skill | Text-only skill directory, with required name and description, packaged through the library engine. Executable, non-text, or symbolic-link companions cause a skip. Foreign audit stamps are not retained. |
+| Prompt or command | Markdown body becomes a Clio prompt. Host execution settings and frontmatter are omitted; the description is retained. |
+| Agent or subagent | Markdown persona or TOML `developer_instructions` becomes a Clio recipe limited to read, grep, find, and ls. Host tools, model, permissions, hooks, and skill bindings are omitted and the plan says so. |
+| Plugin | Accepts a valid portable root `plugin.json`, or a supported `.claude-plugin/plugin.json` / `.codex-plugin/plugin.json` package. Clio adopts a data-only projection of its skills, prompts, agents, and text references. Host extension metadata, hooks, MCP, scripts, tools, fleets, and non-text files are omitted. Dependencies on removed components cause a skip. Package `requires` declarations are preserved; required packages must already be installed, active, and valid in the destination scope. Missing requirements are named in the plan, checked again after approval, and never imported automatically. |
+| Hook, MCP server, executable module, output style | Listed as not adoptable, with a reason. Nothing is registered or executed. |
+
+Claude-only and Codex-only plugin manifests use the same reviewed conversion as
+`library import`. Supported Claude commands become prompts, and Claude agent
+bindings are retained when their required skills convert in the same package.
+Unsupported companions and host features are listed in the plan. A portable
+package is refused when retained recipes require omitted files; for example,
+the tested WTF-P bundle requires action JSON files outside the supported text
+projection. Use ordinary `library install` for a reviewed portable package whose
+complete recipe assets are required, or import supported individual resources.
+
+Installed packages retain `{kind: "interop", host, source}` provenance and
+`trust: "foreign"`, with the original absolute source path. Skill and prompt
+loading keeps the existing `integrations.projectResources.trustProjectImports`
+opt-in, including when a project resource is adopted to user scope. Approval to
+copy a resource does not grant that trust. Same plugin id/version or matching
+installed package content is skipped; identifier collisions are not replaced.
+Library integrity checks, drift detection, disable, and removal apply normally.
+To refresh a foreign source, remove the old library package and review a new adoption plan; no host files are ever
+moved, removed, or modified.
+
+## Inbound: Install or import an explicit foreign package (Claude Code, Codex)
+
+Adoption above starts from what an installed host already has. To install or import an explicit Claude Code plugin or Codex package directly—whether from a local directory or a GitHub repository tree—use `clio-coder library import`:
+
+```bash
+clio-coder library import ./vendor/some-plugin --dry-run
+clio-coder library import https://github.com/owner/repo/tree/main/plugins/thing --project
+clio-coder library import ./vendor/some-plugin --format claude --yes
+```
+
+In an active session, `/library import <path-or-url>` stages and reviews that exact foreign package in the Library. When installing a Claude Code plugin or Codex package, Clio parses the vendor manifest (e.g. `.claude-plugin/plugin.json`) and presents an interactive review before any managed installation or workspace mutation occurs (staging writes temporary inspection files prior to acceptance). The review details four critical facets:
+1. **Source and Provenance**: Displays the verified package source path or repository tree URL, format (`claude-code` or `codex`), and transport.
+2. **Projected Declarative Resources**: Converts text skills (with markdown instructions), commands (converted into prompts), and basic agent personas into native library recipes.
+3. **Foreign Trust Tier**: Marks the package with foreign trust (`trust: "foreign"`). Under Clio's safety model, foreign package skills and prompts—whether installed at project scope or user scope—remain untrusted and withheld from model turns until `integrations.projectResources.trustProjectImports` (`skills.trustProjectCompatRoots`) is enabled. Bound agent recipes require all referenced skills to be trusted.
+4. **Unsupported and Omitted Components**: All executable foreign mechanisms—including MCP servers (`.mcp.json`), lifecycle hooks (`hooks/`), shell scripts (`scripts/`), and daemon runners—are explicitly omitted and listed in the review plan. They are never registered as harness tools or executed.
+
+Cancelling the review cleans up temporary staging files without modifying managed package state or workspace files. The Library's `o` key is the separate route into the local-agent discovery surface below, which starts from what an installed host already has rather than from a source you name.
+
+Detection is deterministic. A root `plugin.json` always takes precedence; an
+invalid root is refused before any vendor fallback. With no root manifest, `.claude-plugin/plugin.json`
+selects the Claude Code format and `.codex-plugin/plugin.json` selects Codex. When
+both hidden manifests are present the import is ambiguous and `--format` is
+required. A directory with none of the three is not importable.
+
+Publication, content validation and the project-import trust gate are reported
+separately. An enabled trust gate is a prerequisite for runtime admission, not
+a claim that every recipe is available.
+
+The same review contract as adoption applies: `--dry-run` prints the projected
+plan and writes nothing, the plan names every converted resource, every
+unsupported host feature and every omitted file, and the source directory is
+never modified. Imported packages install with `trust: "foreign"` and keep
+`{kind: "import", source, transport, format}` provenance, so they stay visibly
+foreign in the library after installation. A skill whose instructions reference a
+companion that was omitted is reported unsupported rather than claimed working.
+
+## Terminal flow
+
+Open `/interop` to inspect inventory or connect an external delegation peer.
+Inventory detail folds behind Enter and wraps in the scrolling detail pane.
+Select a host, press `p` for a project destination or `u` for user, and press `k`
+to cycle the kind filter. Press `i` to review the full adoption plan, then `y`
+to approve it or `b` to return without installing. Escape closes the overlay.
+Connection remains a separate action: `a` connects a proposed peer and `d`
+declines it. `/agents` browses the library's own agent recipes and is a separate
+surface from this one.

package/docs/guide/panes-and-files.md

@@ -20,7 +20,7 @@ Inside a herdr session, Clio can open panes beside itself and close them
 when it quits:
 
 - **The files pane.** A file view docked below the session. `/files` or
-  `Alt+E` opens it and moves the keyboard into it; the same key or command
+  `Alt+E` opens it and moves the keyboard into it; after Ctrl+Y returns focus to Clio, the same key or command
   closes it. Picking a file sends it back to the composer as an `@file`
   mention and returns the keyboard to the prompt. The engine behind it is a
   vendored file manager, installed on request with
@@ -140,7 +140,7 @@ version, or the theme changed since, and the next open regenerates it.
 | Surface | What it does |
 | --- | --- |
 | `/files` | Toggle the files pane: open it below the session and move the keyboard into it, or close it and return the keyboard to the composer. |
-| `Alt+E` | The same toggle as a key (`clio-coder.files.toggle`; `Ctrl+G` then `e` on terminals without Alt). |
+| `Alt+E` | Toggle from Clio focus (`clio-coder.files.toggle`; `Ctrl+G` then `e` on terminals without Alt). |
 | `/files open` | Open the pane, or focus it when it is already open. |
 | `/files close` | Close the pane. |
 | `/files pick` | Borrow the pane for one selection, then close it. Outside herdr, `/files` always behaves this way. |
@@ -174,7 +174,7 @@ the draft`.
 
 ### What closes what
 
-- `/files`, `Alt+E`, and `/files close` close the files pane. A pane the
+- From Clio focus, `/files`, `Alt+E`, and `/files close` close the files pane. Yazi owns its own keys until Ctrl+Y returns the selection and focus. A pane the
   operator closed from herdr is treated as closed the moment herdr reports
   it, so the next toggle opens rather than trying to close a pane that is
   not there.

package/docs/guide/plugins.md

@@ -0,0 +1,80 @@
+# Portable plugins and the library
+
+> **Visual blueprint:** The source checkout includes the complete
+> [Plugins visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/plugins_blueprint.html).
+
+A plugin is a complete, versioned bundle of skills and supporting files. The portable root `plugin.json` follows [Agent Plugins 1.0.0](https://agent-plugins.org/). Clio reads native prompts, agent recipes, and fleets from its namespaced manifest extension. Installing a bundle keeps those resources and their references together.
+
+Browse the bundled catalog, preview a complete installation, then install it:
+
+```bash
+clio-coder library search
+clio-coder library list --kind plugin
+clio-coder library install plugin:materio --dry-run --json
+clio-coder library install plugin:materio
+```
+
+The catalog is shipped with Clio; it does not install content automatically. A preview reports the destination and full-tree SHA-256. The pin covers the manifest, skills, prompts, scripts, references, names, and directory structure. The installer checks the staged bundle again before committing it. If a source changes after the preview, make a new plan. `--force` never overrides a catalog pin mismatch.
+
+For a bundle you authored locally, install its directory directly:
+
+```bash
+clio-coder library install ./my-plugin --project
+clio-coder library inspect my-plugin --project --json
+```
+
+An existing local directory always wins over a catalog ID with the same spelling. `--project` installs into `.clio-coder/plugins/`; the default user scope installs into Clio's configuration directory. Valid, compatible project installations take precedence, including a disabled project installation that suppresses the user copy. The Plugins tab identifies every installed scope and the copy its actions select.
+
+Manage installed content through the same lifecycle functions used by the terminal UI:
+
+```bash
+clio-coder library list --all --json
+clio-coder library disable materio
+clio-coder library enable materio
+clio-coder library drift materio
+clio-coder library pin materio
+clio-coder library update materio
+clio-coder library remove materio
+```
+
+Every successful installation records a verified pin. `pin` reports and verifies it; it does not approve edited files. Drifted content is blocked from loading. Update refuses to replace local edits unless `--force` is supplied; the install result reports any recovery copies of edited content. Updating a catalog package uses the current catalog version and pin. Updating a local package uses its recorded source directory, even when the catalog contains the same plugin name. Updates and replacements preserve an existing disabled state; enable the plugin explicitly when ready. Removal preserves edited content and reports its recovery path.
+
+In an active session, open `/library` or press Alt+L. Use the Plugins category, `b` for Browse or Installed, and `s` for User or Project scope. Enter opens a package's members; the selected row offers `i` to review installation, `u` to review an update, `e` to enable or disable, and `r` to review removal when those actions apply. Use the CLI `library pin` and `library drift` commands for pin and drift checks. Run `/library reload` to refresh resources in that session after changes. The headless `library reload` command refreshes only its own process.
+
+## Private catalogs
+
+The ordinary library catalog supports an `entries` list and plugin entries with explicit versions and pins:
+
+```yaml
+entries:
+  - kind: plugin
+    name: lab-workflow
+    description: Lab analysis workflow and references.
+    version: 1.0.0
+    sourceUrl: ./lab-workflow
+    sha256: <64 lowercase hexadecimal characters>
+```
+
+Relative paths resolve against the catalog's directory. Remote bundles use an explicit GitHub tree URL such as `https://github.com/owner/repository/tree/v1.0.0/plugins/lab-workflow`, together with the full-tree digest and version. The bounded Git transport fetches the selected branch or tag; the installer verifies every bundle file against the catalog pin. Other URL formats are rejected as unsupported. Automatic skill offers select only kind `skill`; they use the same package engine. Catalog `requires` references use the same typed dependency graph as other library entries. Installed plugin dependencies must also be loadable; disabled or damaged dependencies require explicit enabling or repair before installation continues.
+
+Maintainers regenerate the shipped catalog after changing a bundled package:
+
+```bash
+pnpm library:pin
+pnpm library:check
+```
+
+The pin command reads each bundle's actual portable manifest and hashes the complete bundle. `library:check` fails on stale catalog metadata or content digests and is part of release hygiene.
+
+## Plugins and extensions
+
+Recipe plugins and executable harness extensions serve different purposes and have completely distinct lifecycles:
+- **Recipe Plugins**: Managed through `clio-coder library` and `/library`. They package portable declarative components (skills, prompts, agents, fleets, and supporting reference files or explicitly invoked evaluation scripts) using the portable `plugin.json` manifest. While full package trees may carry scripts invoked explicitly by evaluations or workflows, installation, browsing, or loading recipe metadata in the Library never registers executable harness capabilities (such as daemons, background runners, or harness hooks). They install into `.clio-coder/plugins/` (or user `plugins/`). Reloading recipes in an active session is done via `/library reload`.
+- **Harness Extensions**: Managed through `clio-coder extensions` and `/extensions`. They package executable capabilities: an extension operator runtime requires a shipped Node `.mjs` entrypoint (`parseExtensionRuntime` in `src/domains/extensions/runtime-schema.ts`) registering custom slash handlers (`api.handle(...)`), passive lifecycle observations (`events: ["session_open", "turn_end"]`), status indicators, and UI panels. Separately, command tools support `runtime: node` or `python3`, and `hooks.yaml` defines blocking or effect-producing pre-tool/post-tool execution. Extensions install into `.clio-coder/extensions/` (or user `extensions/`). Reloading runtime handlers and hooks at idle is done via `/extensions reload` (subject to integrity checks). However, model-visible command-tool schemas are frozen at session boot and cannot change mid-session; altering tool schemas requires restarting Clio.
+- **Strict Boundary**: The two systems never overlap. An extension manifest attempting to declare domain resources (`skills`, `prompts`, `agents`, `fleets`) is refused and points at `clio-coder library install <path>`. Use `clio-coder extensions list` and `/extensions` to inspect installed extensions. Retired slash commands `/plugins` and `/resources` return an explicit usage error directing operators to `/library` for recipe packages and `/extensions` for harness extensions.
+
+## Other package kinds and evals
+
+The same library supports single-resource skill, agent, prompt and fleet packages. See [library usage](resource-library.md) for registration and JSON state, and [architecture](../architecture/library.md) for the shared invariants. `/library` has all five kinds and `s` switches the selected scope.
+
+Materio declares `extensions["ai.iowarp.clio"].evals.scripts: "evals/scripts.yaml"`. After installation, run `clio-coder eval validate --package plugin:materio --eval scripts` and `clio-coder eval run --package plugin:materio --eval scripts`. This offline suite copies the package to a temporary workspace and runs its Python script contracts. It does not evaluate model research quality.

package/docs/guide/resource-library.md

@@ -1,68 +1,134 @@
-# Resource Library
+# Library packages
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Resource Library visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/resource_library_blueprint.html).
+> **Visual blueprint:** See the [Library visual reference](../html/resource_library_blueprint.html) in the source checkout.
 
-The resource library extends the existing local skills marketplace catalog to carry agent recipes, prompt templates, and fleet contracts. It does not change the Agent Skills format, discovery roots, trust gating, or existing skill installation sources.
+The **library** is Clio's collection of installable **packages**. Each package has one kind: `plugin`, `skill`, `agent`, `prompt`, or `fleet`. Every kind uses a root `plugin.json`, an explicit Semantic Version, a full-tree SHA-256 pin, and the same installation state. A plugin bundles several resources; each other kind exposes one public resource and may include supporting files.
 
-## Catalog schema
+## Browse and install
 
-A catalog is a JSON or YAML list, or an object whose `skills` property contains the list. The historical property name remains accepted so every existing skill marketplace index works unchanged.
+```bash
+clio-coder library list --json
+clio-coder library search research --kind skill
+clio-coder library inspect plugin:materio --json
+clio-coder library install plugin:materio --project --dry-run --json
+clio-coder library install plugin:materio --project --json
+```
+
+`install` is an explicit request to write. `--dry-run` reports every source, destination and digest without installing. The TUI asks for confirmation before writing. `--force` permits replacement of ordinary installed packages and preserves edited files in a reported recovery directory; it cannot override a source pin, identity or version mismatch.
+
+An existing local directory wins over a library name with the same spelling. `kind:name` checks the package kind; bare names are accepted when unambiguous. Package names share one namespace within each scope. A replacement cannot change a package's kind; remove it explicitly first.
+
+## Scope and workspace state
+
+All kinds install beneath `<configDir>/plugins/<name>/` at user scope or `<cwd>/.clio-coder/plugins/<name>/` at project scope. These existing engine directories hold complete packages, including single-resource packages. The corresponding `plugins/state.json` records kind, source, structured origin, trust, installation time and verified digest. There is no per-kind installation pin file.
+
+Install and registration default to user scope. Other lifecycle actions select the project copy when it exists; `--user` or `--project` selects exactly that copy. A valid, compatible project copy takes precedence over the user copy. Disabling that project copy suppresses the user copy as well. Invalid project content does not hide a valid user installation.
+
+`library list --json` returns `{entries, diagnostics}`. Each entry includes an `installed` array containing every matching installed scope and its `enabled`, `valid`, `compatible`, `effective`, and `loadable` state. An empty array means the package is available but uninstalled. Scope flags filter the installed copies. Broken and disabled packages remain visible for repair or removal.
+
+```bash
+clio-coder library disable plugin:materio --project
+clio-coder library enable plugin:materio --project
+clio-coder library drift plugin:materio --project
+clio-coder library pin plugin:materio --project
+clio-coder library update plugin:materio --project --dry-run
+clio-coder library update plugin:materio --project
+clio-coder library remove plugin:materio --project
+```
+
+Drift prevents resources from loading. `pin` verifies and reports the recorded pin; it never blesses local changes. Updates of registered packages use the current index version and pin. Local installations update from their recorded directory. Update and replacement preserve disabled state. Removal preserves edited content and reports the recovery path. Installed state remains addressable after its index entry disappears.
+
+Interop adoption records `{kind: "interop", host, source}` and `trust: "foreign"`. Foreign skills and prompts require `integrations.projectResources.trustProjectImports`, including foreign project files adopted to user scope. Updates and forced replacement of an interop-origin package are refused: remove it and review a new adoption so omitted host executables cannot reappear. See [interoperability](interop.md).
+
+## One index format
+
+The bundled index is `library/registry.yaml`. Clio also reads the user index selected by `integrations.library.catalog` (default `<configDir>/library.yaml`) and the project `.clio-coder/library.yaml`. Project rows override user and bundled rows with the same typed reference; `--from <index>` has highest priority.
+
+Clio Coder ships the index together with its curated `library/skills/` packages and `library/plugins/` bundles in the npm package. Bundled sources resolve relative to the installed index, so they remain available from any working directory without a GitHub fetch. Built-in subagent recipes ship separately under `src/domains/agents/builtins/`; installed plugins can contribute additional recipes and bound skills. The manifest's `ai.iowarp.clio` extension key identifies Clio-specific declarations inside a package, not a marketplace address.
 
 ```yaml
-skills:
-  - kind: fleet
-    name: release
-    description: Build and verify a release.
-    sourceUrl: ./fleets/release.md
+entries:
+  - kind: plugin
+    name: lab-workflow
+    description: Evidence-based laboratory workflow.
+    version: 1.0.0
+    sourceUrl: ./lab-workflow
+    sha256: <64 lowercase hexadecimal characters>
     requires:
-      - agent:release-builder
       - skill:ship
 ```
 
-`kind` accepts `skill`, `agent`, `prompt`, or `fleet` and defaults to `skill`. `requires` accepts typed references with those same four prefixes. Clio resolves requirements recursively across the selected catalog and the private catalog. Missing, malformed, and cyclic requirements are refused with stable `library_requirement_*` diagnostics. A requirement is satisfied when its typed reference exists in `<configDir>/library-pins.yaml` or its kind-specific destination exists. Add output lists satisfied and unsatisfied requirements separately. Requirements are reported without installation unless `library add` receives `--with-requirements`. That flag installs only the unsatisfied dependencies in dependency order before the requested entry.
+An index is JSON or YAML, either an `entries` object or a list. Every row requires kind, name, description, version, source and digest. Relative paths resolve beside the index. Remote sources use explicit GitHub tree URLs, such as `https://github.com/owner/repo/tree/v1.0.0/packages/lab-workflow`; the staged tree must match the pin. Neither opening the library nor registration fetches remote content.
 
-## Private catalog and remote gating
+`requires` contains typed package references and must agree with `extensions["ai.iowarp.clio"].requires` in the package manifest. Missing, malformed and cyclic dependencies are refused. Dependencies must be installed, enabled and loadable; disabled or damaged dependencies require explicit repair. `install --with-requirements` includes missing dependencies in its plan and installs them in dependency order. Each package is atomic; a later package failure does not undo already installed dependencies. Updates require their dependencies to be installed first.
 
-`integrations.library.catalog` selects a private catalog and defaults to `<configDir>/library.yaml`. Relative sources in that file resolve beside the catalog. `integrations.library.remote` records an optional git remote URL. `integrations.library.sync` defaults to false, and no git process is started while it remains false.
+## Register and publish
 
-The private catalog repository must name its git remote `library`. Clio checks it with `git remote get-url library`. Run `clio-coder library remote confirm <url>` once after reviewing the configured URL. When `integrations.library.remote` is unset, confirmation records the URL as both the configured and confirmed remote. A confirmation that differs from an existing `integrations.library.remote` refuses with `library_remote_mismatch`. A missing confirmation or a later settings change refuses synchronization and publishing with `library_remote_unconfirmed`.
+```bash
+clio-coder library validate ./lab-workflow --json
+clio-coder library register ./lab-workflow --project --json
+clio-coder library install plugin:lab-workflow --project
+pnpm library:pin
+pnpm library:check
+```
 
-When `integrations.library.sync` is false, both `library sync` and `library push` refuse with `library_sync_disabled` before any process starts. When synchronization is enabled, `library sync` runs `git fetch library` followed by `git merge --ff-only FETCH_HEAD`, and `library push` runs `git push library`. Both commands execute git as an argument vector without a shell.
+Working authoring templates for all five package kinds live in `library/_authoring/templates/`. Registration validates a local package and writes its identity, version, digest and source into the selected scoped index without installing it. Replacing an existing registration requires `--force`. The maintainer pin command regenerates the bundled index from complete packages in `library/` (`library/skills/` and `library/plugins/`); `library:check` is part of hygiene and verifies all distributed bytes against `library/registry.yaml`. For curated skills, `skills:pin` records normalized skill-body hashes as provenance evidence. See [authoring a package](authoring-plugins.md) and the [architecture invariants](../architecture/library.md).
 
-## CLI
+`library:pin` also regenerates `.claude-plugin/marketplace.json` from those pins, which is what lets another agent install these packages from the repository: `claude plugin marketplace add iowarp/clio-coder`, then `claude plugin install <name>@clio-coder`. Codex reads the same canonical directories through `.agents/skills`. Neither surface holds a copied recipe body, and `library:check` fails on a stale one. A package publishes there only when a peer host would load a real skill surface from it and nothing it would default-scan into a native component; the pin run prints which packages it left out and why, and leaving one out is not a failure. See [coding agent interoperability](interop.md).
 
-```text
-clio-coder library list [--kind k] [--json]
-clio-coder library search <query> [--kind k] [--json]
-clio-coder library add <ref> [--from <catalog|path>] [--with-requirements] [--yes] [--json]
-clio-coder library use <kind> <name>
-clio-coder library push
-clio-coder library sync
-clio-coder library remote confirm <url>
-```
+Private index repositories may opt into Git synchronization. Set `integrations.library.sync: true`, configure a remote named `library`, and review `clio-coder library remote confirm <url>`. `library sync` fetches that remote and merges `FETCH_HEAD` with `--ff-only`; `library push` pushes it. Disabled synchronization or an unconfirmed/mismatched remote refuses before mutation. These commands synchronize the private repository; they do not automatically update installed packages.
 
-`library add` prints every destination and SHA-256 hash before it writes. It writes nothing until `--yes` is present. `library use` prints the invocation to paste into the relevant surface.
+## Keyboard shortcuts: Alt+L for Library and Alt+M for Model picker
 
-## In the TUI
+Clio provides default top-level keyboard shortcuts from the composer:
+- **Alt+L**: Toggles the Library overlay (`clio-coder.library.toggle`). Pressing **Alt+L** while inside the Library closes it and returns focus to your active composer draft.
+- **Alt+M**: Toggles the Model picker overlay (`clio-coder.model.select`), allowing you to switch models, view token budgets, or configure reasoning effort.
+- **Alt+W**: Toggles the Workers / dispatch board overlay (`clio-coder.dispatchBoard.toggle`).
+- **Ctrl+G**: Opens the contextual leader action menu when focused in the composer, offering single-key actions (such as `l` for Library, `m` for Model picker, `w` for Workers dispatch board, and `s` to background attached dispatch).
 
-The Skills Hub carries one tab per kind. `/resources library <kind>` opens the
-requested tab, while `/skill` opens Skills. Each tab lists discovered entries
-and any unresolved requirements. Installing from a row uses the same
-plan-then-write path as `clio-coder library add`, behind a confirmation that
-states every destination and hash and writes nothing when cancelled. `Enter`
-on an installed row leads to its invocation surface. See
-[Skills Marketplace](skills-marketplace.md) for the key table.
+These are default shortcuts subject to configured keybinding overrides and focused modal ownership (see [Commands and Modes](commands-and-modes.md#keybindings)).
 
-## Installation roots and validation
+## Interactive library navigation
 
-| Kind | User installation root | Validation before write |
-| --- | --- | --- |
-| skill | `<configDir>/skills/<name>/SKILL.md` | Existing skill loader and installer |
-| agent | `<configDir>/agents/<name>.md` | Agent recipe schema and policy |
-| prompt | `<configDir>/prompts/<name>.md` | Prompt template loader |
-| fleet | `<configDir>/fleets/<name>.md` | Fleet contract parser |
+**Alt+L** or `/library` opens the fullscreen Library; `/skills`, `/agents`, and `/prompts` open its corresponding category. The five tabs cover skills, agents, prompts, fleets, and plugins. `b` switches Browse/Installed, and `s` selects User/Project for management. Mode and scope remain visible on empty tabs. Left/right changes category; `/` focuses search, where letters and left/right edit the query. Enter returns from search to the list; Esc clears search or returns before closing.
 
-Every installed item records a kind-qualified hash in `<configDir>/library-pins.yaml`. Agent recipes become visible through `clio-coder agents`. User fleet contracts participate between built-in and project fleet precedence, so a project contract still wins. Prompts use the existing user prompt root.
+Enter opens a package's members. `v` uses an available recipe by preparing its invocation in the composer; a fleet opens its existing approval preview. `i` reviews installation, `u` update, `e` enable/disable, and `r` removal. A member's management action names its whole owning package and the selected scope. Core and loose recipes have no package removal action. `o` opens local-agent discovery and reviewed adoption; `R` rereads the browser inventory. Pin and drift inspection remain available through the CLI.
+
+`/library inspect <ref>`, `/library install <ref>`, `/library remove <ref>`, and `/library import <path-or-url>` open the same browser and review flow; use typed references such as `skill:tdd` and an explicit `--user` or `--project` when needed. Import reviews the supplied source, its supported recipes and omitted features. Origin, vendor format, trust, scope and actual availability are separate facts; an installed foreign package may still have recipes withheld by the trust setting.
+
+Every managed change is reviewed before writing. The review shows dependencies, affected dependents, fallback behavior and recovery, with `d` revealing paths and digests. Esc cancels and releases staged sources. Outcomes report committed, failed and unattempted steps, disk verification, resource admission and session refresh separately. A failed refresh does not undo a committed write; `R` in the outcome retries refresh without repeating the mutation.
+
+## Session reload and package disable behavior
+
+`/library reload` refreshes installed recipes (skills, prompts, agents, fleets) in the active running session. If an external CLI command or file edit changes installed recipes, `/library reload` reloads the inventory without needing a restart. In headless mode, `library reload` refreshes only its own process.
+
+When you disable a package (via `library disable <ref>` or pressing `e` in the Library overlay):
+- The package state in `plugins/state.json` is updated with `enabled: false`. No files are deleted.
+- Resource discovery and admission exclude disabled recipes on subsequent reads (`enabledPluginResourceRoots` in `src/domains/plugins/resources.ts` rechecks current installation state on the next read, even before a manual session reload). A CLI disable does not broadcast cancellation into other running processes, stop an in-flight tool, or erase instructions already in model context.
+- If a project-scope copy of a package is disabled, it explicitly suppresses any matching user-scope copy as well, ensuring that the project's intent to disable the capability is honored.
+- Re-enabling the package with `library enable <ref>` restores resource discovery. Adding or replacing recipes requires a session refresh; active UI management actions report their own refresh results, while `/library reload` reloads the inventory for the current session.
+
+Contrast with harness extensions: executable harness extensions carry Node operator runtimes, command tools (Node or Python), and lifecycle hooks. Running `/extensions reload` refreshes extension runtime handlers, hooks, and panels at idle (subject to integrity verification), but command-tool schemas are frozen at session boot and cannot change mid-session.
+
+`/skills` opens the skill tab; `/skill <name>` activates a skill, `/skill off` clears the active skill's armed tool surface (without erasing instructions already loaded in transcript or context), and bare `/skill` returns usage guidance pointing to `/skills`. `library skills --all --json` lists runtime skills, including unmanaged files; `library inventory --json` is the fixed body-free GUI read. `clio-coder library validate <path>` validates an unmanaged draft or a complete package candidate. Installed package lifecycle remains in `library`; retired slash commands `/plugins` and `/resources` return an explicit usage error directing operators to `/library` for recipe packages and `/extensions` for harness extensions.
+
+## One inventory for the operator and the model
+
+```bash
+clio-coder library recipes --json
+clio-coder library recipes materials --kind agent
+clio-coder library recipes --source core --all
+```
+
+`library recipes` is the versioned, body-free read of the recipes actually discovered here, across every source: bundled core recipes, loose user and project files, installed package members, and foreign files in interop compatibility roots. Each row carries its actual runtime name, its owning package or source class, its scope, its origin evidence, its availability and, where it is usable, its invocation. It never fetches a remote source and never writes. `library list` and `library search` stay package-oriented and answer with install targets; `--kind agent` there also matches packages whose generated `provides` hints include an agent, so a kind query finds the owning bundle before installation. `library inventory --json` is unchanged: it remains the fixed skills wire contract that GUI hosts read.
+
+Clio reads the same inventory through `context(scope="library")`. That scope is a read: bounded `kind`, `query` and `ref` selection with `limit`/`offset` pages, tagged rows for loaded resources, catalog hints and install targets, and no activation, installation, registration or pin write anywhere in it. Skill activation stays under `context(scope="skills")` and `/skill <name>`. A hint row names its installable owner and that member's honest state and never carries an invocation, because nothing has loaded it. Internal and shadow agents, untrusted resources and instruction bodies are not in the model's view at all, and a worker run has no library projection of its own. See [tool usage](tool-usage.md) for the argument surface and the row shapes.
+
+A package declares named suite paths in `extensions["ai.iowarp.clio"].evals`. Run the same eval interface for every kind:
+
+```bash
+clio-coder eval validate --package plugin:materio --eval scripts --project
+clio-coder eval run --package plugin:materio --eval scripts --project
+```
 
-Share archives may carry agent and fleet entries. Import always validates these formats before writing, and fleet entries land in the user fleet root.
+Evals run only when explicitly requested. Installed packages must be active and verified; local authoring directories can be tested directly. The resulting suite provenance includes the package reference, version, digest and eval name. Materio's `scripts` suite runs its offline Python contracts in a temporary copy; it measures script behavior, not model output quality. The separate experimental `eval skill <name|path>` lane runs authored `evals.md` baseline/treatment/judge scenarios.