@iowarp/clio-coder 0.4.6 → 0.4.7

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.

package/docs/guide/skills-marketplace.md

@@ -1,93 +1,56 @@
-# Skills Marketplace
+# Skills in the library
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Skills Marketplace visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/skills_blueprint.html).
+> **Visual blueprint:** See the [Skills visual reference](../html/skills_blueprint.html) in the source checkout.
 
-The Skills Hub (`/skill`) shows project skills, user skills, and the marketplace. Every marketplace row comes from the same local lookup that `clio-coder skills install <name>` and `/skill <name>` resolve through, so the hub lists nothing it cannot install.
+Skills are one kind of [library package](resource-library.md). `/skills` opens the Library overlay's skill tab directly, while `/library` opens the full overlay (covering skills, plugins, agents, prompts, and fleets). `/skill <name>` invokes a skill, and `/skill off` clears the session's active tool surface; bare `/skill` returns usage guidance pointing to `/skills`. Skill packages use the same manifest, version, full-tree digest, origins, scope and lifecycle as every other package.
 
-## Operator ownership of installed skills
-
-The active project `.clio-coder/skills/` tree and the resolved user `<configDir>/skills/` tree are operator-owned. Main-agent and worker tool admissions refuse writes, edits, artifacts and recognized shell mutations to either tree, including ancestor deletion and current symlink aliases. This boundary stays active at every autonomy level, even when the general default path policy is disabled. Reads and loading already installed skills retain their existing rules.
-
-Draft a proposed skill outside these active trees, for example in `draft-skills/`. The operator installs or updates it through `clio-coder skills install`, `skills update`, `skills sync`, `library add --yes`, the Skills Hub, `/skill <name>`, or an explicitly accepted marketplace offer. Even `full-auto` must wait for that offer's bound operator answer; a task match alone no longer installs a skill. Model shell calls to recognizable Clio skill installation, update and sync commands are refused. Confirmed `library add --yes` commands are also reserved for operators, including additions of other resource kinds that may install skill dependencies. An unconfirmed `library add` only prints a plan and remains available, as do inventory, search, inspection and validation commands.
-
-This is a tool-admission boundary, not an operating-system sandbox. Shell inspection covers literal paths and recognized command forms, respecting comments, quoted words and redirection operands when identifying Clio commands. Quoted search patterns remain read-only, and literal operator filenames do not hide later mutation operands. It cannot prove the effects of arbitrary scripts, dynamically constructed paths, aliases, or concurrent filesystem changes. Keep shell execution supervised when stronger confinement is required.
-
-## Where marketplace rows come from
-
-There is one source, `discoverMarketplaceSkills()` in `src/domains/resources/skills/marketplace.ts`, and it reads two kinds of real local data:
-
-1. **A catalog directory** of actual `SKILL.md` packages. Resolution order: `CLIO_CODER_SKILL_CATALOG_DIR`, then a `skills/` directory in the working tree when it holds packages, then the `skills/` catalog the installed clio-coder package carries. Metadata comes from the packages themselves through the skill loader, so a row's version, category, and audit state are the package's own.
-2. **A JSON index** whose entries name a `sourceUrl` that `clio-coder skills install` accepts. Resolution order: `CLIO_CODER_SKILL_MARKETPLACE_INDEX`, then `<configDir>/skill-marketplace.json`, then the package's own `skills/skill-marketplace.json`. `pnpm run skills:pin` publishes that file's `version`, `audit`, and `category` fields.
-
-The package fallbacks mean a fresh npm install has a marketplace with no configuration: `clio-coder skills search grill` lists `grill-me` from the shipped catalog, `clio-coder skills install grill-me` copies it out of the package into `.clio-coder/skills/`, and `/skill grill-me` offers that install before running. The shipped catalog is a marketplace source only, never a discovery root: nothing from it is loadable until the operator installs it, which keeps the install-then-activate contract and the per-skill scope choice in the operator's hands.
-
-Catalog packages win over index entries on a name collision, because the local files are the thing that installs. Neither source reaches the network; the hub opens on local data and never blocks. Only an index entry whose `sourceUrl` is a GitHub URL, and that no catalog also carries, needs the network at install time.
-
-The model sees the same lookup: `context(scope="skills")` lists installed skills and, under a `Marketplace (not installed)` heading, the entries this lookup would install. Loading a marketplace-only skill by name answers "not installed" and points at `/skill <name>`, never `unknown skill`.
-
-When both sources are absent (a source checkout with no `skills/` folder, or an incomplete package) the hub has nothing to list and says so, naming the remedy:
-
-```
-no skills installed and no local marketplace configured. install one with
-`clio-coder skills install <path|github-url>`, or point CLIO_CODER_SKILL_CATALOG_DIR at a
-skills/ catalog.
+```bash
+clio-coder library search grill --kind skill
+clio-coder library install skill:grill-me --project --dry-run
+clio-coder library install skill:grill-me --project
+clio-coder library skills --all --json
 ```
 
-The CLI reports the same state as `no local skill marketplace catalog or index configured`. A marketplace source that exists but fails (an unreadable index, a broken catalog package) is a diagnostic row in the hub, not a silent omission.
-
-The same index machinery can also describe agent recipes, prompt templates, and fleet contracts through typed entries and requirements. See [resource-library.md](resource-library.md) for the schema, private catalog, installation roots, and `clio-coder library` commands. Those kinds render on their own tabs in the hub, described below.
-
-## Using the hub
-
-| Key | Action |
-|---|---|
-| type | Filter all groups |
-| `←`/`→` | Switch tabs |
-| `Enter` | Use the selected row: insert `/skill <name> ` into the editor for the task text, or the invocation the row's kind is called by |
-| `Tab` | Toggle the detail pane (split layout on wide terminals) |
-| `i` | Install the selected row through the resolver its kind installs by |
-| `PgUp`/`PgDn` | Scroll the detail pane |
+The bundled index makes complete packages available without installing them. An ordinary packaged skill copies from Clio's shipped files without network access. Local user and project registrations can add packages. Automatic offers and `/skill <name>` use the same library entries and package installer. An unmanaged `SKILL.md` remains a valid runtime resource; preparing a distributable requires a package manifest as described in [authoring](authoring-plugins.md).
 
-Invoking an uninstalled marketplace skill with `/skill <name>` prompts before installing it. `i` runs the same install path eagerly from the hub.
-
-## Tabs
+## Operator ownership of installed skills
 
-The hub carries one tab per resource-library kind: Skills, Agents, Prompts, and
-Fleets. `←` and `→` move between them. The frame title names the active tab and
-the footer states its row count, so the numbers on screen always describe the
-tab being read. `/skill` opens Skills; `/resources library <kind>` opens the
-requested library tab.
+Active `.clio-coder/skills/`, `<configDir>/skills/`, and managed package trees are operator-owned. Main and worker tool admission refuses recognized model writes, edits, deletes and shell mutations to those trees at every autonomy level. Library install, update, registration, enable/disable, removal and pin actions are reserved for the operator; install/update `--dry-run`, search, inspection and draft validation remain available. This is a tool-admission boundary, not an operating-system sandbox for arbitrary scripts or dynamically constructed shell commands.
 
-The Skills tab is unchanged. The other three list the entries of their kind from `discoverLibrary()`, which is the same discovery `clio-coder library list --kind <kind>` reads, so the hub and the CLI never disagree about what exists. Each row carries the entry's origin and version, whether it is installed or available, the short form of its recorded pin hash, and, in the warning token, the names of any requirements it still needs. An entry the catalog refuses outright, because a requirement is missing, malformed, or cyclic, appears as a diagnostic row rather than being omitted.
+Draft outside active roots, for example `draft-skills/example/`. The operator can review `library validate draft-skills/example/SKILL.md`, then register and install a complete package. Explicitly accepted skill offers install through the library. A lexical match alone never grants installation authority, including at `full-auto`.
 
-`Enter` uses the selected row. An agent inserts `/run <agent> ` into the composer, a prompt inserts its `/<id> ` invocation, a skill does what the Skills tab does, and a fleet closes the hub and opens the `/fleet run` approval preview for that contract. A row that is not installed says so instead and points at `i`.
+## Library keys and runtime use
 
-`i` installs, through the same plan-then-write pair `clio-coder library add` runs. A framed confirmation states every destination path and SHA-256 hash before anything is written, which is the TUI spelling of the CLI's `--yes` gate; `Esc` there leaves every destination untouched. An entry whose requirements are not all installed is refused by name on the first `i`, and a second `i` opens the install-with-requirements confirmation, which names every entry it would write in dependency order.
+| Key | Action |
+| --- | --- |
+| Type | Filter rows |
+| Left / Right | Change kind tab |
+| `s` | Switch user/project action scope |
+| `Enter` | Use a selected runtime resource or inspect a plugin |
+| `i` | Review installation; a second request can include missing requirements |
+| `u` | Review update |
+| `e` | Enable or disable the selected installed copy |
+| `r` | Review removal |
+| `p` | Verify and show the recorded package pin |
+| `d` | Check installed drift |
+| `Esc` | Close or cancel |
 
-The CLI `clio-coder skills` commands manage local skill discovery, validation, and
-creation. Extension resource roots and share archives are documented in
-[extensions-and-sharing.md](extensions-and-sharing.md); this page owns the TUI
-Hub and marketplace behavior.
+`/skill <name> [task]` activates a skill; `/skill off` clears the session's tool-surface narrowing. Loading can narrow allowed tools but cannot grant tools the host disallows. At `read-only` and `suggest`, activation requires an operator request; `auto-edit` and `full-auto` may activate installed skills. Listing available skills does not load their bodies.
 
-## Remote entries and overlays
+Model-visible skills must be trusted and permit model invocation. Foreign project resources and all interop-adopted foreign skills require `integrations.projectResources.trustProjectImports`. A project resource adopted into user scope retains foreign trust. Disabled, incompatible or drifted package resources do not load. `/library reload` refreshes an active session after a lifecycle change.
 
-Some skills are worth carrying in the catalog without vendoring their content. `skills/remote.yaml` lists them: each entry names a skill, its category, a `sourceUrl` that must be a GitHub tree URL at a pinned tag, an `overlay` package inside the catalog, and an optional `exclude` list of upstream top-level members. `pnpm run skills:pin` publishes such an entry into `skills/skill-marketplace.json` with `origin: "remote"`, the upstream URL as its `sourceUrl`, and the `overlay` and `exclude` fields attached. The overlay's `SKILL.md` is pinned in `skills/registry.yaml` like every other catalog skill, so `pnpm run skills:check` fails when it drifts.
+For duplicate skill names or paths, trusted candidates take precedence over untrusted candidates. An untrusted `.claude/skills` or `.agents/skills` copy cannot hide a trusted Library installation. Normal scope precedence still decides between trusted copies, including project compatibility roots the operator explicitly trusts. A named load of an untrusted or manual-only skill reports that restriction instead of claiming the skill is unknown.
 
-`archify` is the worked example. Its entry points at `https://github.com/tt-a1i/archify/tree/v2.16.0/archify`, overlays `skills/planning/archify`, and excludes `test` and `package-lock.json`. Running `clio-coder skills install archify --project` clones that tag, drops the excluded members, copies the overlay over the clone so Clio's wrapper `SKILL.md` replaces the upstream one, validates the shaped tree, and swaps it into `.clio-coder/skills/archify/` with the usual provenance stamps. The renderer, its schemas, and its brand-mark notices come from upstream at install time and never enter the npm tarball. The wrapper omits upstream's update-awareness step on purpose: that step performs a network request during a chat turn, and no Clio chat turn depends on the network.
+## Matching, authoring and evals
 
-Discovery treats the overlay folder as part of the remote entry rather than as a skill of its own, so a bare-name install never lands the wrapper without the renderer it wraps. `clio-coder skills update` recovers the same overlay and exclude list from the marketplace, so an update refetches the pinned upstream and re-applies the wrapper instead of replacing it.
+Authored whole-phrase triggers rank before incidental name or description overlap. Matches are lexical suggestions, not evidence that a model will offer or successfully use a skill. Headless sessions emit passive library-install guidance and do not open an interview. Interactive offers require a bound operator answer.
 
-Two operational notes. A copy dropped into a project-scope `.claude/skills/archify` is a compat import and stays untrusted until `integrations.projectResources.trustProjectImports` is on; install through Clio to get a trusted, provenance-stamped copy. And since the skill's authoring loop is several `bash` calls (validate, deliver, verify), `auto-edit` is the sensible permission posture for a mapping session; full manual approval works but prompts on every command.
+House skills live in `library/skills/<category>/<name>/`, with `SKILL.md`, a package `plugin.json`, and authored `evals.md` scenarios. `skills:check` checks authoring metadata and normalized audit evidence; `library:check` verifies the distributable's complete tree. Only the latter is an installation pin. Explicit catalog-directory and old skill-index probes remain available to authoring utilities for unmanaged source audits; automatic library installation does not use those as a separate installer.
 
-Architecture mapping through Archify follows a structured pipeline across distinct stages: deterministic structural seed generation (`clio-coder context map`), model-authored refinement, deliverable validation (`validate`, `deliver`, profile checks, and Clio verifiers), and review. Clio derives the deterministic architecture seed from the structural codewiki without model calls; Archify validates and renders the model's semantic refinements. Standard validation checks schema conformance and layout composition, while verification commands check path and symbol citations against the workspace. Mechanical validation passes do not establish semantic claims or visual layout quality: source review assesses semantic claims, while visual review in a browser assesses layout presentation. Custom model-authored maps can remain layout-invalid until iteratively refined.
+Named suite evals use `clio-coder eval run --package skill:<name> --eval <suite>`. The experimental `clio-coder eval skill <name|path>` runs `evals.md` baseline, treatment and model-judge scenarios. Fixture commands require `--trust-fixtures`; network tools remain off unless `--allow-network` is requested. Those measurements are separate from deterministic package validation.
 
 ## Publishing a skill
 
-Add a directory under `skills/<category>/<name>/` (or `skills/<name>/`) in the repo containing a `SKILL.md` with `name` and `description` frontmatter. The directory name must match `[A-Za-z0-9][A-Za-z0-9._-]*`. Run `pnpm run skills:pin` to republish `skills/skill-marketplace.json`, which is the index consumers point `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at or copy to `<configDir>/skill-marketplace.json`. Scientific and niche coding domains are the marketplace's focus; see the existing `skills/` tree for the house format.
-
-## Matching and offers
-
-Authored whole-phrase triggers rank before incidental description or name overlap. Matching remains lexical: interactive offer guidance asks the model to check installed alternatives and relevance before presenting an offer. A match does not guarantee that a model will offer or use the skill.
+To publish a skill, prepare a complete skill package with `SKILL.md` and a portable root `plugin.json`. Declare kind `skill`, an explicit Semantic Version, the skill resource root and one public skill component. Validate the package with `clio-coder library validate ./my-skill`, then register its local source with `clio-coder library register ./my-skill --project`. Registration records its full-tree digest without installing it. Install the candidate with `clio-coder library install skill:<name> --project` and verify its behavior before sharing.
 
-Interactive offers require a bound operator answer before installation. Headless runs emit a passive installation hint; that reminder opens no interview and performs no installation or activation. Installing a skill makes it discoverable; listing it or supplying an explicit skill path makes it available, while loading its body remains subject to activation policy. At `read-only` and `suggest`, activation requires an operator request; `auto-edit` and `full-auto` may activate installed skills. A suggestion alone continues the task without activation.
+For a curated contribution, add the reviewed package beneath `library/skills/<category>/<name>/`, include authored eval scenarios, and regenerate both the skill authoring records (`pnpm skills:pin`) and complete library package pins (`pnpm library:pin`). A shared remote index must name an explicit supported GitHub tree source, version and full-tree SHA-256. The [package authoring guide](authoring-plugins.md) defines the manifest and index fields; publishing does not itself install or activate the skill for another operator.

package/docs/guide/tool-usage.md

@@ -14,7 +14,7 @@ context) share one result envelope, implemented in `src/tools/observation.ts`.
 The OBSERVE policy plane also contains `credential_present`, whose deliberately
 minimal result does not use that envelope.
 
-Per-call byte caps: read 50KB (`safety.limits.readBytesPerCall`), grep 16KB for mode=content and 8KB for mode=files/count, find 8KB, ls 8KB, code_nav 16KB, context 16KB for scope=docs and 50KB for scope=skills/workspace.
+Per-call byte caps: read 50KB (`safety.limits.readBytesPerCall`), grep 16KB for mode=content and 8KB for mode=files/count, find 8KB, ls 8KB, code_nav 16KB, context 16KB for scope=docs and scope=library, and 50KB for scope=skills/workspace.
 
 Truncated text results append exactly one notice line:
 
@@ -428,16 +428,19 @@ git(op="diff", path="src/tools/safe-exec.ts")
 git(op="log", limit=10)
 ```
 
-## context: workspace snapshot, docs retrieval, and skills
+## context: workspace snapshot, docs retrieval, skills, and the library catalog
 
-One OBSERVE entry point for material about the working environment rather than the tree itself. Sources: `src/tools/context/index.ts`, `src/tools/context/docs-engine.ts`.
+One OBSERVE entry point for material about the working environment rather than the tree itself. Sources: `src/tools/context/index.ts`, `src/tools/context/docs-engine.ts`, `src/tools/context/library.ts`.
 
 Arguments:
 
-- `scope` (required). `workspace`, `docs`, or `skills`.
-- `query` (scope=docs). Question or terms; omit to list the corpus (files plus doc/section counts) instead of searching.
-- `limit` (scope=docs). Max sections; default 5, max 12.
+- `scope` (required). `workspace`, `docs`, `skills`, `library`, or `recall`.
+- `query` (scope=docs). Question or terms; omit to list the corpus (files plus doc/section counts) instead of searching. At scope=library, name, owner, or description terms.
+- `limit` (scope=docs). Max sections; default 5, max 12. At scope=library, max rows; default 20, max 50.
 - `name` (scope=skills). Skill to load; omit to list.
+- `kind` (scope=library). One of `skill`, `agent`, `prompt`, `fleet`, or `plugin`.
+- `ref` (scope=library). An exact `kind:name` package reference, a resource key, or a bare runtime name.
+- `offset` (scope=library, scope=recall). Zero-based; follow the reported `nextOffset`.
 - `include_tree` (scope=skills, boolean). List up to 50 files under the skill's base_dir.
 
 `scope="workspace"` returns the session's git/project snapshot as JSON, probing and caching it on first call. When model-visible skills are installed, the payload carries a one-line `skills` pointer (count plus the suggest protocol) so orientation surfaces the catalog; the pointer never includes catalog entries and never changes the load gate. It requires a bound session; worker registries without one get a clean error. 50KB cap.
@@ -449,11 +452,18 @@ vocabulary aliases, phrase boosts, and BM25-style body scoring. The JSON payload
 
 `scope="skills"` with no `name` lists installed skills with descriptions. A matching suggestion uses `Suggested skill: /skill <name>` and continues the task without activating a skill. At `read-only` and `suggest`, loading requires an explicit operator request; at `auto-edit` and `full-auto`, policy permits activation of installed skills without that request. Recipe-bound workers may load only their declared skills. Installation, availability, and activation are separate: even `full-auto` requires a bound operator acceptance for a marketplace installation. A pending request's task text is surfaced with the body. Marketplace-installed skills are drift-checked against their pinned hash; a mismatch annotates the result with a `skill_drift` warning but never blocks. 50KB cap; a truncated body offloads in full.
 
+`scope="library"` is the read-only recipe catalog, backed by the same bounded inventory `clio-coder library recipes --json` reads, and it activates, installs, registers and pins nothing. Rows are tagged and never mixed up with one another. A `resource` row is a recipe that actually loaded: its runtime name (skill frontmatter name, agent recipe id, prompt path with colons, fleet contract name), owning package or `core`/`user`/`project`/`compat` source class, scope, origin evidence, format, and the invocation that works. A `hint` row is a catalog claim about one member of a package: it names the owning package, that owner's installed copy states, and the member's own state (`not-installed` when the owner is not installed, `unknown` when the owner is installed and the member did not turn up), and it never carries an invocation because nothing loaded it. A `package` row is the install target itself with its version, origin, installed copies, and bounded `provides` hints; a package with no hints reports its contents as unknown until inspection rather than empty.
+
+The model view is the model audience: internal and shadow agents, untrusted, invalid, shadowed and manual-only resources are not listed. `kind="plugin"` returns plugin-kind install targets only; any recipe kind returns the loaded resources of that kind plus the installable owners that provide it, so an Agents or Prompts query finds the owning bundle before it is installed and without fetching its source. `ref` may match one exact resource key, several same-named records across kinds (the payload says so and each row carries its `key`), or a package, which opens that package's members. A run started with `--no-skills` lists no skill rows, because nothing in it can load one. Instruction bodies and absolute recipe paths are never returned. 16KB cap: the page is fitted to the remaining budget before it is rendered, so `limit` is an upper bound and `nextOffset` carries the remainder; `total` counts what the inventory returned and is flagged `totalIsLowerBound` when the inventory hit its own record cap. Worker registries have no library projection of their own and get a clean unavailable error.
+
 ```text
 context(scope="workspace")
 context(scope="docs", query="dispatch receipts evidence", limit=8)
 context(scope="skills")
 context(scope="skills", name="context-prime", include_tree=true)
+context(scope="library", kind="agent", query="materials")
+context(scope="library", ref="plugin:materio")
+context(scope="library", limit=20, offset=20)
 ```
 
 ## code_nav: navigate the codewiki index
@@ -725,6 +735,8 @@ Arguments:
 
 The tool manages a stateful operator interview. The UI presents choices (with an implicit "Other" option for custom text input). Once completed, the final decisions are persisted as standard configurations in the session ledger, allowing the agent to proceed with operators' inputs or defaults.
 
+What the operator sees is one box above the composer, sized to the round: the question header, the question with bold spans and hanging numbered lists, then every option with its whole description. A round of several questions names them all in a strip at the top. A question longer than the box scrolls with PgUp/PgDn while its options stay on screen. Enter records the focused option; `t` records it and opens a multi-line answer field (Shift+Enter for a newline, Esc back to the options); an option whose label says the operator will type, such as "Provided details" or "Other", opens the field on Enter. Space toggles a multi-select option, Left/Right move between the questions of a round, `a` opens the answers recorded so far, and `?` shows the decision's tier, effect, and reversibility. Each answered round is recorded in the transcript as the question headers and the answers.
+
 Ask only when blocked on a decision the request does not answer. Never ask about anything the operator already stated: a request that names its own scope ("all tools", "read only") has answered the interview before it starts.
 
 ```text
@@ -745,7 +757,7 @@ Arguments:
 
 `kind=plan|review|report` writes a Markdown document to `.clio-coder/artifacts/PLAN.md`, `REVIEW.md`, or `REPORT.md` by default, so a turn nobody asked a file from never litters the working tree; `path` may override the destination but must stay inside the workspace. See [artifact-placement.md](../architecture/artifact-placement.md) for the full contract. When `content` does not already start with `#`, a non-empty `title` is prepended as an H1. These kinds are TERMINAL: writing the artifact completes the turn and the harness skips the follow-up model call, so the artifact body itself is the answer. Put everything the reader needs in `content`; there is no closing message after the write.
 
-Skills are not artifacts. A skill is a `SKILL.md` folder written with the ordinary write tool into `.clio-coder/skills/<name>/` (or the user skill store) and validated by the skills loader; the `skill-craft` shipped skill documents the format and craft rules.
+Skills are not artifacts. A skill is a `SKILL.md` folder, and the active skill trees (`.clio-coder/skills/`, `.clio-coder/plugins/`, `.clio-coder/extensions/`, and their user-scope counterparts) are operator-owned: model-side writes and deletes there are refused, reads are not. Draft a skill somewhere else in the workspace, check it with `clio-coder library validate <path>`, and leave installation to the operator through `clio-coder library install` or `/library`. The `skill-craft` shipped skill documents the format and craft rules.
 
 ```text
 artifact(kind="plan", content="# Migration plan\n\n## Step 1 ...")

package/docs/guide/troubleshooting.md

@@ -16,7 +16,7 @@ diagnostics in the current source tree.
 | `clio-coder run cannot confirm permission requests; rerun interactively to approve this action.` | A tool call required manual permission confirmation during a non-interactive headless `clio-coder run` execution. | Run the command interactively in the TUI (`clio`) to grant one-shot approval, adjust the workspace policy in `.clio-coder/safety.yaml`, or run with `--autonomy full-auto` if safe. |
 | `no trace database yet at <path>` | The trace mirror database has not been initialized because no interactive sessions or dispatches have executed yet. | Execute a turn or dispatch a task. In SQLite trace commands, this notice is informational (exit code `0`). |
 | `trace database not found: <path>` | An explicit `--db <path>` flag was provided pointing to a nonexistent database file. | Verify the database path or omit `--db` to use the default state directory database (`<stateDir>/trace.sqlite`); the next line prints that default path. |
-| `no local skill marketplace catalog or index configured` | No catalog directory (`CLIO_CODER_SKILL_CATALOG_DIR`, a `skills/` folder in the working tree, or the installed package's own `skills/` catalog) and no JSON index (`CLIO_CODER_SKILL_MARKETPLACE_INDEX`, `<configDir>/skill-marketplace.json`, or the package's `skills/skill-marketplace.json`) was found. On an npm install this means the package is incomplete; check `clio-coder doctor`. | Point `CLIO_CODER_SKILL_CATALOG_DIR` at a `skills/` catalog or `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at a valid `skill-marketplace.json`, or install a skill directly via `clio-coder skills install <path\|github-url>`. |
+| `no local skill marketplace catalog or index configured` | No catalog directory (`CLIO_CODER_SKILL_CATALOG_DIR`, a `library/skills/` folder in the working tree, or the installed package's own `library/skills/` catalog) and no JSON index (`CLIO_CODER_SKILL_MARKETPLACE_INDEX`, `<configDir>/skill-marketplace.json`, or the package's `library/skills/skill-marketplace.json`) was found. On an npm install this means the package is incomplete; check `clio-coder doctor`. | Point `CLIO_CODER_SKILL_CATALOG_DIR` at a `library/skills/` catalog or `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at a valid `skill-marketplace.json`, or install a skill directly via `clio-coder library install <path\|github-url>`. |
 | `<arg> is a global option and must come before the subcommand: clio-coder <usage> <command> ...` | A global CLI option (such as `--api-key`, `--no-context-files`, or `-nc`) was placed after the subcommand name. Directory roots are configured via `CLIO_CODER_*_DIR` environment variables. | Move the flag before the subcommand name (e.g. `clio-coder --api-key <key> run ...` instead of `clio-coder run --api-key <key> ...`). |
 | `target <id> is not registered` | The designated target ID does not exist in `settings.yaml`. | Run `clio-coder targets` to view available targets, or configure a new target using `clio-coder targets add`. |
 | `budget: ceiling must be >= 0 (got <val>)` | A negative session cost ceiling reached the scheduling budget (`src/domains/scheduling/budget.ts`). | Set a non-negative `safety.limits.sessionCostUsd` in `settings.yaml`, or edit Session ceiling (USD) in Settings → Budget. |