@iowarp/clio-coder 0.4.6 → 0.4.8

package/docs/guide/harness-extensions.md

@@ -0,0 +1,289 @@
+# Harness extensions
+
+Harness extensions add executable capabilities to Clio. Library recipes may also carry explicitly invoked workflow or evaluation scripts. Installing or browsing a recipe never registers harness tools, hooks, operator commands, or UI. A domain workflow that combines prompts, agents, skills, fleets, and reference files is a plugin, installed with `clio-coder library install <path>`.
+
+An extension declares command tools in `clio-coder-extension.yaml`, `.yml`, or `.json`. Clio discovers and validates declarations without importing or executing package code. Tools become available in a new session after installation. Native workers can use a tool when their admitted recipe includes its qualified name; narrower profiles such as `minimal-local` exclude extension commands.
+
+## Create a command tool
+
+Create a directory containing this `clio-coder-extension.yaml`:
+
+```yaml
+id: local-analysis
+name: Local Analysis
+version: 1.0.0
+description: Local analysis capabilities for Clio.
+compatibility:
+  clio: ">=0.4.7"
+capabilities:
+  tools:
+    - name: summarize
+      description: Return the count and sum of supplied measurements.
+      runtime: node
+      entrypoint: tools/summarize.cjs
+      timeoutMs: 10000
+      maxOutputBytes: 16384
+      inputSchema:
+        type: object
+        properties:
+          values:
+            type: array
+            items:
+              type: number
+            maxItems: 1000
+        required: [values]
+        additionalProperties: false
+```
+
+Add `tools/summarize.cjs`:
+
+```javascript
+const { values } = JSON.parse(process.argv[2]);
+console.log(JSON.stringify({
+  count: values.length,
+  sum: values.reduce((sum, value) => sum + value, 0),
+}));
+```
+
+Install the directory and start a new Clio session:
+
+```bash
+clio-coder extensions install /path/to/local-analysis --user
+clio-coder extensions list --all --json
+clio-coder
+```
+
+The model can call `extension_local-analysis__summarize` with `{"values":[1,2,3]}`. A recipe requests that same qualified name in `tools.required` or `tools.optional`. Python tools use `runtime: python3` and read `json.loads(sys.argv[1])`; Clio launches Python with `-I` to isolate interpreter configuration.
+
+## Command contract
+
+Each tool declares `name`, `description`, `runtime`, `entrypoint`, and `inputSchema`. Supported runtimes are `node` and `python3`. Clio uses its current Node executable and resolves `python3` from the normal tool environment. Entrypoints are ordinary files inside the installed package; symlinks, hard links, absolute paths, and parent traversal are refused. Helper files remain covered by the full package digest.
+
+Clio passes the validated JSON object as one argument and runs a fixed argument vector with no shell. The child runs in the workspace directory. Standard output must contain exactly one JSON value. Use standard error for diagnostics. Nonzero exits, invalid JSON, cancellation, timeout, and exceeded output limits return tool errors with execution metadata and package provenance.
+
+Input is limited to 64 KiB. `timeoutMs` defaults to 120000 and is bounded at 300000. `maxOutputBytes` defaults to 600000 and is bounded at 1048576. Output limits include standard output and standard error together.
+
+Schemas support `type`, `description`, `properties`, `required`, `additionalProperties`, `items`, scalar `enum`, `minimum`, `maximum`, `minLength`, `maxLength`, `minItems`, and `maxItems`. The root must be an object. Each object declares its properties and `additionalProperties: false`; array schemas declare `items`. References and executable schema keywords are refused. Clio validates each invocation against the schema before starting the child.
+
+Qualified names use `extension_<id>__<name>` and must fit 64 characters. Package IDs use provider-safe lowercase letters, numbers, single underscores, and hyphens; local tool names start with a letter and use lowercase letters, numbers, and single underscores. Duplicate and colliding tool registrations are refused.
+
+The manifest keys are `id`, `name`, `version`, `description`, `capabilities`, `compatibility`, and optional `runtime` (described below). A manifest naming `resources`, `prompts`, `skills`, `agents`, `fleets`, or `themes` is invalid, and the diagnostic points at `clio-coder library install <path>`. `capabilities` is optional: a package whose only contribution is a root `hooks.yaml` is a valid harness extension with no command tools.
+
+## Admission and lifecycle
+
+Every model-visible extension command tool is an execution action and runs sequentially. Packages cannot declare themselves read-only. The registry evaluates both the qualified capability call and its fixed executable command through Clio's existing safety policy, autonomy, approval, and middleware rules. Read-only autonomy blocks commands; workers with explicit write confinement cannot execute an unconfined extension command. Installation does not bypass command approval. The child receives Clio's normal allowlisted tool environment, which excludes provider credentials and interpreter injection variables.
+
+Command tools are installed programs with the filesystem and network access of the invoking process. Entry containment and environment filtering do not create an operating-system sandbox. Install code you trust, as you would a local executable script.
+
+The existing extension lifecycle applies:
+
+```bash
+clio-coder extensions disable local-analysis --user
+clio-coder extensions enable local-analysis --user
+clio-coder extensions install /path/to/new-local-analysis --user --force
+clio-coder extensions remove local-analysis --user
+```
+
+Installation records and verifies the entire package tree. Each invocation rechecks the effective installed package, enabled state, canonical root, and digest. Disabling, removing, replacing, or modifying a package revokes existing tool calls. A disabled project installation also suppresses the user installation with the same ID.
+
+## Extension reload: runtime capabilities, integrity verification, and frozen session tool schemas
+
+Harness extensions distinguish reloadable runtime capabilities from frozen model tool definitions:
+- **Reloading at idle (`/extensions reload`)**: Extension snapshots, hooks declared in `hooks.yaml`, and operator runtimes reload at idle when the session is not executing tools or commands. `/extensions reload` re-reads installed extension files and re-verifies tree integrity against `extensions/state.json`. Reload is **not unconditionally successful**: if an installed package file has been modified on disk without being properly reinstalled via `clio-coder extensions install`, it fails integrity checks and reports degraded runtime activation. Similarly, if the active process limit (up to 4 child processes) is exceeded or staging is interrupted by session activity, reload reports a failure or queues until idle.
+- **Operator runtimes vs command tools**: An extension operator runtime (`api.handle(...)`, `api.on(...)`) requires a shipped Node `.mjs` entrypoint (`parseExtensionRuntime` in `src/domains/extensions/runtime-schema.ts`) and provides bounded status indicators and UI panels. Its `session_open` and `turn_end` events are passive observations, fundamentally distinct from effect-producing, blocking pre-tool/post-tool interceptors in `hooks.yaml`. Separately, harness command tools execute individual tool invocations under either `runtime: node` or `python3`.
+- **Capabilities that require a new session**: Model-visible command-tool schemas are frozen when a session starts. Adding a new command tool, modifying its parameter schema, or removing a tool cannot alter an in-flight conversation or worker registry; restart Clio to pick up tool schema changes.
+- **Recipe resources vs extensions**: Recipe resources (skills, prompts, agents, fleets) belong to the Library, not harness extensions, and are refreshed independently via `/library reload`. A new native worker constructs its own verified registry, and ordinary allowed-tool surfaces and worker attestation apply. External command-line worker runtimes do not gain Clio command tools.
+
+## Operator commands, status, and panels
+
+An optional `runtime` adds local code-backed slash commands and observations in
+an interactive session. It uses a fresh disposable Node child per package.
+Discovery, installation, validation and `extensions list` remain code-free.
+Installing or enabling trusted runtime code makes it eligible to execute on the
+next interactive startup or explicit extension reload. Module initialization,
+commands and observations run with your user account's filesystem and network
+authority, independently of model-tool autonomy. The API provides no tool,
+provider, credential, model, worker or session mutation methods. This is
+lifecycle isolation, not an operating-system sandbox.
+
+```json
+{
+  "id": "lab-status",
+  "name": "Local experiment status",
+  "version": "1.0.0",
+  "description": "Inspect local experiment records.",
+  "compatibility": { "clio": ">=0.4.7" },
+  "runtime": {
+    "api": 1,
+    "entrypoint": "extension.mjs",
+    "commands": [{ "name": "dashboard", "description": "Show local experiment status." }],
+    "events": ["session_open", "turn_end"],
+    "ui": ["status", "panel"]
+  }
+}
+```
+
+Only `.mjs` entrypoints are supported. Ship JavaScript and contained assets;
+author TypeScript with your own build if desired. Clio never installs
+dependencies or runs package lifecycle scripts. Each runtime loads from a
+private copy whose complete digest matches the reviewed installation. Contained
+relative helpers and assets are copied and refreshed too. Mutable external
+imports, native add-ons, detached subprocesses, remote state, and files written
+by the extension are outside the reload guarantee.
+
+The default export registers exactly the declared commands and observations.
+Registration closes when the factory settles; it cannot add tools or new
+commands later. Import author types with
+`import type { ExtensionApi, ExtensionOutput } from '@iowarp/clio-coder/extensions'`.
+This package export contains types only; Clio injects the implementation.
+
+```javascript
+/** @param {import('@iowarp/clio-coder/extensions').ExtensionApi} api */
+export default function extension(api) {
+  api.handle("dashboard", (_args, context) => {
+    context.signal.throwIfAborted();
+    return {
+      text: "SYNTHETIC FIXTURE: 2 of 3 jobs completed",
+      status: { text: "SYNTHETIC: 2/3 completed", tone: "neutral" },
+      panel: {
+        title: "Synthetic experiment",
+        sections: [
+          { kind: "metrics", items: [{ label: "Completed jobs", value: "2/3" }] },
+          { kind: "text", text: "Demonstration data; no cluster jobs were submitted." }
+        ]
+      }
+    };
+  });
+  api.on("session_open", () => ({ text: "", status: { text: "Synthetic fixture ready" } }));
+  api.on("turn_end", () => ({ text: "" }));
+  api.onDispose(() => { /* best-effort local cleanup */ });
+}
+```
+
+Commands receive the unexpanded argument string and a context with `signal`,
+`requestId`, and a read-only snapshot of `workspace`, `sessionId`, `generation`
+and `mode`. No conversation body, tool arguments or credentials cross this
+API. Results render locally for the operator and never start a model turn or
+become a session transcript entry. The required `text` is also the headless
+fallback; include the same useful findings and evidence qualifiers there.
+
+`session_open` receives a `startup`, `reload`, or `session-change` reason.
+`turn_end` receives `completed`, meaning the foreground turn settled, not that
+its scientific or engineering objective passed validation. Observers are
+asynchronous observations, distinct from effect-producing `hooks.yaml`.
+Observers may return status, but cannot open a panel or steal focus. There is
+one coalesced pending observation; a busy runtime skips observations. No timer
+polling or arbitrary event bus subscription API is exposed. Runtime globals
+reset on reload and on resume, fork, workspace change or branch switch.
+
+UI is bounded data. A status is one string (160 characters) and an optional
+`neutral`, `positive`, `warning`, or `error` tone; `status: null` clears it.
+The footer displays a single additive line with host-assigned owner labels;
+core activity, approval cues and notices retain ownership. The Extensions
+reference shows each owner's full current status if the footer truncates it.
+Panels support plain text, labeled metrics, and tables. Clio owns wrapping,
+scrolling, Escape, focus and permission interruption. Terminal controls are
+stripped. Background code cannot open panels; a command opens one only when
+no other overlay needs the screen. An unavailable panel falls back to text.
+Panels expire with their instance and close on observed revocation when they
+hold the overlay slot; an interrupted expired panel shows an expiry message.
+
+## Invoke and manage operator runtimes
+
+```bash
+# From the source checkout, or use the examples directory in the installed package:
+clio-coder extensions install examples/extensions/lab-status --project
+clio-coder extensions list --all --json
+clio-coder extensions run lab-status dashboard
+clio-coder extensions run lab-status dashboard --json -- /path/to/local-record.json
+```
+
+Inside an interactive session, invoke `/ext:lab-status:dashboard` or append a
+local JSON filename. Browse `/extensions` and use
+`/extensions reload` after a reviewed reinstall or enable. These are the canonical
+harness routes; `/library extensions` and `/library extensions reload` are retired.
+`/library reload` refreshes recipe resources independently and never loads runtime code.
+
+Canonical commands use `/ext:<extension-id>:<command>`. Existing extension IDs
+are preserved, including dots and underscores. Local command names start with
+a lowercase letter and contain lowercase letters, digits or underscores.
+There are no short aliases. Built-ins retain ownership; an existing prompt
+with the same canonical spelling remains a prompt and disables that extension
+command with a conflict diagnostic. This includes unavailable and display-only
+prompts. Completion and dispatch share that collision projection. Avoid `ext:`
+when authoring new prompt names. Unknown canonical commands error; escaped
+`\/ext:...` remains ordinary model text.
+
+`extensions run` is the explicit headless operator path. It starts only the
+selected installed runtime, supplies `sessionId: null`, sends no synthetic
+session observation, prints one fallback or JSON result, then disposes the
+runtime. SIGINT/SIGTERM cancel it. A CLI invocation does not reload any other
+running session. Ordinary `clio-coder run`, ACP sessions and native workers do
+not start operator/UI runtimes. They retain existing admitted command tools;
+a slash token is not permission to run an operator extension in a worker.
+
+Installation eligibility, extension snapshot/hook generation, operator runtime
+readiness and model tool schemas are separate facts:
+
+- Listing says `eligible`, not that another process has activated the package.
+  The live Extensions reference reports runtime state, generation, failures,
+  available commands and current status. Tool evidence is taken from the actual
+  session registry when that host provides it. Other hosts explicitly label the
+  comparison as a runtime-startup observation, which does not prove a model
+  schema binding.
+- Idle reload restarts every child using verified copies. During reload,
+  commands are unavailable. Reload requested during a turn, command, local
+  shell operation or modal interaction is queued to an idle boundary.
+- The existing synchronous snapshot/hook pair still commits together. Runtime
+  staging happens first, then that pair commits, then the runtime generation
+  publishes and children acknowledge activation. Startup/handler failures are
+  reported as degraded runtime state. A rejected reload leaves no replacement
+  runtimes active; old children are already stopped and require a retry.
+  This deliberately does not promise atomic rollback of arbitrary code or
+  preserve module globals across reloads.
+- Each command rechecks installed scope, enabled state, canonical root and
+  whole-tree digest before and after execution. A slow host tick also observes
+  revocation while idle. No timer or scan runs when there are no active runtimes
+  or pending reloads. Active runtimes receive a full admission check at a
+  30-second minimum interval, lengthened to at least 100 times the last scan
+  duration on slower filesystems. Checks may therefore be delayed on HPC/shared
+  storage. Commands and observations still verify before and after execution;
+  the slow timer is only proactive revocation detection. Once observed, old
+  requests and UI lose authority and the child is disposed. Disable/remove is
+  scoped; a disabled project copy suppresses a user copy, while project removal
+  may reveal it on reload. Installation, enable and update need explicit reload
+  to start newly eligible code.
+- Tool schemas stay frozen. **Editing only UI in a mixed tool/runtime package
+  changes the full package digest and revokes that session's old tool calls.**
+  Reinstalling and reloading the UI cannot rebind those calls. Start a new
+  session, or keep rapidly developed UI in a separate runtime-only package.
+  Existing declarative extension hooks retain captured generations until reload;
+  they do not acquire the command tools' per-invocation digest recheck.
+
+At most four runtimes run concurrently; further eligible packages show a limit
+diagnostic. There are at most 32 commands, two observations and eight disposal
+callbacks per runtime. Startup/activation each have a 5-second deadline;
+commands default to 30 seconds and may declare `timeoutMs` from 100 through
+300000. Observations have a 2-second deadline. Arguments are limited to 16 KiB;
+results to 64 KiB (text 32768 characters), and protocol messages to 96 KiB and
+128 messages per second. Panels have at most 16 sections, 32 metric items,
+8 table columns and 100 rows per table. stdout/stderr are discarded as
+non-protocol diagnostic streams and their combined 64 KiB lifetime cap fails
+the runtime. Failures are bounded diagnostics, not arbitrary terminal output.
+
+Cancellation fences the result immediately, signals the handler, allows
+250 ms of best-effort disposal, then kills the child. Timeouts/protocol failures
+kill it directly. Linux/macOS process groups also stop ordinary descendants;
+Windows has direct-child termination only. A detached daemon, external job,
+already-written file, or an unresponsive child after an ungraceful parent death
+cannot be reclaimed by this lifecycle contract. No OS containment is claimed.
+
+## Scientific examples
+
+[The worked examples](../../examples/extensions/README.md) are included in the
+npm package. `lab-status` reads a bounded local JSON experiment record and uses
+an explicitly synthetic fixture by default. It performs no SSH, provider calls,
+remote cluster queries or submissions. `measurements` is a separate existing
+command-tool package that computes count, mean, extrema and sample standard
+deviation of supplied finite numbers. Units and provenance stay caller-supplied;
+a singleton's sample standard deviation is unavailable (`null`).

package/docs/guide/installation-and-lifecycle.md

@@ -1,8 +1,5 @@
 # Installation and Lifecycle Operations
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Installation and Lifecycle Operations visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/lifecycle_blueprint.html).
-
 Clio Coder installs from the npm registry as `@iowarp/clio-coder` using npm,
 pnpm, or Bun, or from a source checkout using the pinned pnpm workflow. The
 [README installation guide](../../README.md#install) covers global installs,
@@ -48,7 +45,7 @@ npm install -g @iowarp/clio-coder --omit=optional
 # Or: bun add -g @iowarp/clio-coder --omit=optional
 ```
 
-Measured on Linux x64 with a production install (`--omit=dev`): 387MB across 118 packages with the SDK, 143MB across 109 packages without it. That is 244MB and nine packages saved, a 63% smaller tree, and what remains is fully open-licensed.
+Historical Linux x64 measurement before the web package integration (`--omit=dev`): 387 MB across 118 packages with the SDK, 143 MB across 109 packages without it. Treat those numbers as a comparison, not the current install size: the platform, dependency versions and optional packages change the total. The release tarball size excludes separately installed npm dependencies.
 
 Everything except the `claude-sdk` runtime works on the smaller install: boot, `clio-coder doctor`, every other target and worker runtime. Dispatching a `claude-sdk` target on an install that omitted the package fails that run with a diagnostic naming the package and the command that fixes it (`npm install @anthropic-ai/claude-agent-sdk@0.3.186`); nothing else degrades, and nothing fails at startup.
 
@@ -96,7 +93,8 @@ The tables above cover the per-user roots. A repository Clio works in also grows
 | `.clio-coder/profile.yaml` | Operator input | Operator profile; closed enums and bounded path lists. | Yes. | Kept |
 | `.clio-coder/fleets/*.md`, `.clio-coder/fleets/commands.yaml` | Overlay | Fleet contracts and their command registry. Adds to the fleets shipped under `src/domains/agents/fleets/`. | Yes; shipped fleets remain. | Kept |
 | `.clio-coder/agents/*.md` | Overlay | Project agent recipes. Composes with shipped builtins and the user's `~/.config/clio-coder/agents`; a project recipe reusing a builtin id is **ignored**, not applied, with a note on stderr. | Yes; shipped agents remain. | Kept, and named |
-| `.clio-coder/skills/**` | Overlay | Project skills, trusted as repository-local. This is where `clio-coder skills install <name>` lands a catalog skill; the shipped catalog under the package's `skills/` is a marketplace to install from, not a discovery root, so nothing appears here until the operator installs it. | Yes; the shipped catalog remains installable. | Kept, and named |
+| `.clio-coder/skills/**` | Overlay | Loose project skills placed here by the operator, trusted as repository-local. Library installations use the managed package store below. | Yes; loose skills must be restored by the operator. | Kept, and named |
+| `.clio-coder/plugins/<name>/`, `.clio-coder/plugins/state.json` | Operator input | Complete installed library packages of all five kinds and their scoped state. `clio-coder library install skill:<name> --project` installs here. The bundled `library/` remains the catalog source. | Use `clio-coder library remove <kind>:<name> --project` to keep package state consistent. | Kept, not named |
 | `CLIO-CODER.md` (repository root) | Runtime state | The generated project handbook. Human-reviewable, but written by `context init`. | Yes; regenerate with `clio-coder context init`. | Kept unless `--all` |
 | `.clio-coder/codewiki.json` | Runtime state | Structural index, schema v5. | Yes; rebuilt by `clio-coder context index`. | **Removed** |
 | `.clio-coder/state.json` | Runtime state | Index fingerprint and freshness stamps. | Yes; forces a rebuild. | **Removed** |
@@ -110,12 +108,12 @@ The tables above cover the per-user roots. A repository Clio works in also grows
 user configuration directory, not in any repository.
 
 None of `.clio-coder/` is published by Clio's own package. The directories Clio ships
-(`src/domains/agents/builtins/`, `src/domains/agents/fleets/`, the whole `skills/` catalog
-with its `registry.yaml` and `skill-marketplace.json`, `src/domains/prompts/fragments/`,
+(`src/domains/agents/builtins/`, `src/domains/agents/fleets/`, the whole `library/` catalog
+with its registry, recipe packages and skill provenance records, `src/domains/prompts/fragments/`,
 `src/domains/providers/models/`) are read from the installed package root; the `.clio-coder/`
 entries above compose with them and never replace them on disk. Builtin agent recipes bind
 skills straight out of the package catalog; the operator's own session reaches the same
-catalog only as a marketplace, through `clio-coder skills install <name>` or `/skill <name>`.
+catalog only as a marketplace, through `clio-coder library install skill:<name>` or `/skill <name>`.
 
 ---
 
@@ -252,13 +250,12 @@ sessions; the uninstall operation below deliberately removes those roots.
 
 #### Current migration contract
 
-The v0.4.2 source tree registers five migrations in execution order:
+The source tree registers four migrations in execution order:
 
 1. `2026-09-01-settings-v2`
-2. `2026-09-01-extension-install-digests`
-3. `2026-09-01-clio-coder-naming`
-4. `2026-09-01-retire-panes-knobs`
-5. `2026-08-18-lmstudio-runtime-id`
+2. `2026-09-01-clio-coder-naming`
+3. `2026-09-01-retire-panes-knobs`
+4. `2026-08-18-lmstudio-runtime-id`
 
 Applied IDs are recorded in `<stateDir>/migrations.json`. An ID already in that
 manifest is skipped, and each successful migration is recorded immediately so a

package/docs/guide/interop.md

@@ -0,0 +1,241 @@
+# Coding agent interoperability
+
+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

@@ -1,8 +1,5 @@
 # Panes and the Files Pane
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Panes and the Files Pane visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/panes_files_blueprint.html).
-
 This page is the operator's path from a clean machine to a working files pane
 beside a Clio Coder session: what to install, how a session joins its pane
 host, the commands and keys, the settings that govern them, what `doctor`
@@ -20,7 +17,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 +137,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 +171,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.